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

# Buy email server

> Buy an email server, paid as one unit of the plan's price on the workspace's subscription. Spends money. With an active subscription the unit joins it on its own cycle and the prorated amount for the rest of the period is charged to its card in the call (409 payment_declined buys nothing); item is the new server in provisioning, run shows the build. Without one nothing is charged: item is null and checkout holds a Paddle checkout only the app can open, so the user pays on the Email Accounts screen (search_billing_subscriptions tells which case applies). A seat delete_email_box kept (retained subscription_seat) goes to the next server of its plan, free. Through MCP it takes two calls: the first, without commit_token, changes nothing and has no price quote; the second, same arguments plus commit_token, buys. The REST route takes no commit_token and buys on the call. Not idempotent: each confirmed call buys another server. 503 email_servers_not_offered: this deployment sells none. Requires can_manage_billing.

Contract:
- MCP tool `create_email_box`, registry package `mcp.id/email_boxes`, mount `id.billing`.
- Operation `create`, response envelope `create`.
- Flags: dangerous: the MCP layer gates it behind a preview/commit token, and the effect cannot be undone through this API.



## OpenAPI

````yaml /api-reference/id/openapi.yaml post /api/email-boxes
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-boxes:
    post:
      tags:
        - email_boxes
      summary: Buy email server
      description: >-
        Buy an email server, paid as one unit of the plan's price on the
        workspace's subscription. Spends money. With an active subscription the
        unit joins it on its own cycle and the prorated amount for the rest of
        the period is charged to its card in the call (409 payment_declined buys
        nothing); item is the new server in provisioning, run shows the build.
        Without one nothing is charged: item is null and checkout holds a Paddle
        checkout only the app can open, so the user pays on the Email Accounts
        screen (search_billing_subscriptions tells which case applies). A seat
        delete_email_box kept (retained subscription_seat) goes to the next
        server of its plan, free. Through MCP it takes two calls: the first,
        without commit_token, changes nothing and has no price quote; the
        second, same arguments plus commit_token, buys. The REST route takes no
        commit_token and buys on the call. Not idempotent: each confirmed call
        buys another server. 503 email_servers_not_offered: this deployment
        sells none. Requires can_manage_billing.


        Contract:

        - MCP tool `create_email_box`, registry package `mcp.id/email_boxes`,
        mount `id.billing`.

        - Operation `create`, response envelope `create`.

        - Flags: dangerous: the MCP layer gates it behind a preview/commit
        token, and the effect cannot be undone through this API.
      operationId: create_email_box
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEmailBoxRequest'
      responses:
        '200':
          description: '`create` success envelope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEmailBoxResponse'
        4XX:
          $ref: '#/components/responses/McpClientError'
        5XX:
          $ref: '#/components/responses/McpServerError'
components:
  schemas:
    CreateEmailBoxRequest:
      type: object
      description: Request body of `create_email_box`.
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 60
          description: The server's label, 1 to 60 characters.
        plan:
          type: string
          enum:
            - starter
            - growth
            - agency
            - dedicated
          description: >-
            Mailboxes per plan: starter 100, growth 500, agency 2000, dedicated
            10000.
        location:
          type: string
          enum:
            - hel1
            - fsn1
            - nbg1
          description: hel1 Helsinki, fsn1 Falkenstein, nbg1 Nuremberg.
        copy_settings_from:
          type: string
          nullable: true
          minLength: 18
          maxLength: 18
          pattern: ^em_bx_
          description: >-
            A serving server of this workspace whose settings and stop-list the
            new one starts with. Omitted: the stop-list comes from the oldest
            active server.
      required:
        - name
        - plan
        - location
    CreateEmailBoxResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        operation:
          type: string
          enum:
            - create
        item:
          type: object
          nullable: true
          properties:
            sid:
              type: string
            team_sid:
              type: string
            name:
              type: string
              description: The label the customer chose; "Server N" when nobody did.
            plan:
              type: string
              enum:
                - starter
                - growth
                - agency
                - dedicated
              description: >-
                Mailboxes per plan: starter 100, growth 500, agency 2000,
                dedicated 10000.
            location:
              type: string
              nullable: true
              enum:
                - hel1
                - fsn1
                - nbg1
              description: Null on a server older than the choice.
            status:
              type: string
              enum:
                - provisioning
                - active
                - suspended
                - resizing
                - destroying
                - destroyed
                - failed
              description: >-
                resizing from the moment a plan change is accepted, destroying
                from the moment a delete is.
            suspended_reason:
              type: string
              nullable: true
              enum:
                - payment_failed
                - unpaid
              description: >-
                payment_failed: the subscription is past due beyond its grace,
                or paused. unpaid: more servers of the plan than paid units.
            complimentary:
              type: boolean
              description: >-
                The server granted without a paid unit; it cannot be resized or
                deleted.
            seats_cap:
              type: integer
              minimum: 0
              description: Mailboxes the server can hold.
            seats_used:
              type: integer
              minimum: 0
              description: Mailboxes it holds now.
            ipv4:
              type: string
              nullable: true
            release:
              type: string
              nullable: true
              description: The gtm.service.email release the server runs.
            run:
              type: object
              nullable: true
              properties:
                verb:
                  type: string
                  description: >-
                    provision, rescale, migrate, suspend, resume, destroy,
                    rotate_secrets, tenant_push or move_accounts.
                status:
                  type: string
                  description: >-
                    pending, running, succeeded, failed or cancelled. failed is
                    terminal until retry_email_box_run resumes it.
                phase:
                  type: string
                  nullable: true
                phase_index:
                  type: integer
                  minimum: 0
                  description: 1-based among phase_count; 0 before the first phase started.
                phase_count:
                  type: integer
                  minimum: 0
                started_at:
                  type: string
                  nullable: true
                error_code:
                  type: string
                  nullable: true
              required:
                - verb
                - status
                - phase
                - phase_index
                - phase_count
                - started_at
                - error_code
              description: >-
                The newest unfinished lifecycle run of the server, else its
                newest run when that one failed, else null.
            price:
              type: object
              nullable: true
              properties:
                amount:
                  type: string
                  description: Decimal string, e.g. "49.00".
                currency:
                  type: string
                  description: ISO 4217.
                interval:
                  type: string
                  description: month or year.
              required:
                - amount
                - currency
                - interval
              description: >-
                The plan's unit price on the subscription's cycle. Null for the
                complimentary server, without a live subscription and once the
                server is leaving.
            renews_at:
              type: string
              nullable: true
              description: The subscription's next billing date.
            paid_through:
              type: string
              nullable: true
              description: 'Set by a delete: the end of the period the server was paid for.'
            failed_error_code:
              type: string
              nullable: true
            created_at:
              type: string
              nullable: true
            provisioned_at:
              type: string
              nullable: true
            suspended_at:
              type: string
              nullable: true
            updated_at:
              type: string
              nullable: true
          required:
            - sid
            - team_sid
            - name
            - plan
            - location
            - status
            - suspended_reason
            - complimentary
            - seats_cap
            - seats_used
            - ipv4
            - release
            - run
            - price
            - renews_at
            - paid_through
            - failed_error_code
            - created_at
            - provisioned_at
            - suspended_at
            - updated_at
        already_exists:
          type: boolean
        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
        checkout:
          type: object
          nullable: true
          properties:
            client_side_token:
              type: string
              nullable: true
            paddle_environment:
              type: string
            paddle_transaction_id:
              type: string
              nullable: true
          required:
            - client_side_token
            - paddle_environment
            - paddle_transaction_id
          description: >-
            Set instead of item when the workspace has no subscription: the
            purchase finishes in the app.
      required:
        - success
        - operation
        - item
        - already_exists
        - meta
        - checkout
    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.