Botmail Mailboxes API

openapi: 3.2.0
info:
  title: Botmail Mailboxes API
  version: 1.0.0
  summary: Gmail for AI agents.
  description: 'Real email mailboxes for AI agents. Agents claim an address with

    `POST /v1/claim`, a human claims it in the browser, then the same API key

    reads, sends and manages mail.


    **Errors** always look like `{"error": {"code", "message", "hint?", "details?"}}`.

    `code` is stable and machine-readable; `hint` says what to do next.

    429 responses carry `Retry-After` (seconds).


    **IDs** are prefixed strings: `acct_`, `mbx_`, `thr_`, `msg_`, `key_`, `clm_`.

    Times are RFC 3339 UTC.


    **Scopes**: `read`, `send`, `manage`. Pending claim keys (`bm_pending_…`)

    have `read` + `invite` until a human claims the mailbox, then they gain

    full access in place. `send` is dropped while the account is not `active`.

    Each operation lists its required scope.'
servers:
- url: https://botmail.pro
security:
- bearerAuth: []
- cookieAuth: []
tags:
- name: mailboxes
  description: Mailboxes and name availability.
paths:
  /v1/domains:
    get:
      tags:
      - mailboxes
      operationId: listDomains
      summary: List mail domains
      description: 'No auth needed. Any listed domain can be passed as `domain` to

        POST /v1/claim or POST /v1/mailboxes. The primary domain is the web

        origin. Paid plans get the same name on every domain.'
      security:
      - {}
      responses:
        '200':
          description: Mail domains.
          content:
            application/json:
              schema:
                type: object
                required:
                - domains
                properties:
                  domains:
                    type: array
                    items:
                      type: object
                      required:
                      - domain
                      - primary
                      properties:
                        domain:
                          type: string
                          example: musemail.pro
                        primary:
                          type: boolean
                  hint:
                    type: string
  /v1/names/{name}:
    get:
      tags:
      - mailboxes
      operationId: checkName
      summary: Check name availability
      description: 'No auth needed. Signed-in callers get answers for their plan (short

        names); anonymous and pending callers get free-plan answers.

        Rate limit: 60/minute per IP.'
      security:
      - {}
      - bearerAuth: []
      - cookieAuth: []
      parameters:
      - name: name
        in: path
        required: true
        description: Local part to check (normalized to lower case).
        schema:
          type: string
      responses:
        '200':
          description: Availability. `message` and `hint` are set when unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NameCheck'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/mailboxes:
    get:
      tags:
      - mailboxes
      operationId: listMailboxes
      summary: List mailboxes
      description: 'Scope: read. Pending claim keys allowed. Only mailboxes the credential can access, oldest first.'
      responses:
        '200':
          description: Mailboxes.
          content:
            application/json:
              schema:
                type: object
                required:
                - mailboxes
                properties:
                  mailboxes:
                    type: array
                    items:
                      $ref: '#/components/schemas/Mailbox'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      tags:
      - mailboxes
      operationId: createMailbox
      summary: Create a mailbox
      description: 'Scope: manage. Claimed (human) accounts only, with an unrestricted

        credential. 402 plan_limit at the plan''s mailbox limit; 422

        invalid_name / name_reserved / short_name / invalid_domain /

        invalid_display_name; 409 name_taken / name_held / name_retired.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              additionalProperties: false
              properties:
                name:
                  type: string
                  maxLength: 32
                  description: '1-32 chars: a-z, 0-9, ''.'', ''-'', ''_''; starts and ends with a letter or digit. 4 or fewer chars need a paid plan.'
                domain:
                  type: string
                  description: A Botmail domain. Defaults to the primary domain.
                display_name:
                  type: string
                  maxLength: 64
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mailbox'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
  /v1/mailboxes/{id}:
    parameters:
    - $ref: '#/components/parameters/IdPath'
    get:
      tags:
      - mailboxes
      operationId: getMailbox
      summary: Get a mailbox
      description: 'Scope: read. Pending claim keys allowed.'
      responses:
        '200':
          description: The mailbox.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mailbox'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - mailboxes
      operationId: updateMailbox
      summary: Update a mailbox
      description: 'Scope: manage. Not for pending keys. display_name is the sender name

        on outgoing mail; empty clears it (mail then shows the mailbox name).

        The address can''t be changed: passing name or address returns

        422 address_permanent.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                display_name:
                  type: string
                  maxLength: 64
      responses:
        '200':
          description: The updated mailbox.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mailbox'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'
    delete:
      tags:
      - mailboxes
      operationId: deleteMailbox
      summary: Delete a mailbox and all its mail
      description: 'Scope: manage. Not for pending keys. Irreversible. The name is held for 7 days.'
      responses:
        '200':
          description: Deleted.
          content:
            application/json:
              schema:
                type: object
                required:
                - deleted
                - id
                - freed_bytes
                - name_held_until
                properties:
                  deleted:
                    type: boolean
                    const: true
                  id:
                    type: string
                  freed_bytes:
                    type: integer
                    format: int64
                  name_held_until:
                    type: string
                    format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Conflict:
      description: Conflicts with current state.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request (`bad_request` or a more specific code).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PaymentRequired:
      description: Plan limit or payment needed (`plan_limit`, `payment_required`). Upgrade, then retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid credentials (`unauthorized`, `invalid_token`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unprocessable:
      description: Well-formed but rejected; see `code` and `hint`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: 'The credential can''t do this (`forbidden`, `csrf`, `account_inactive`, …).

        Missing scopes are listed in `details.required_scope`; pending keys get

        a hint to wait for the claim.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Not found or not accessible with this credential.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Too many requests (`rate_limited`, `invite_limit`). Wait `Retry-After` seconds.
      headers:
        Retry-After:
          description: Seconds to wait.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Mailbox:
      type: object
      required:
      - id
      - name
      - display_name
      - status
      - address
      - addresses
      - created_at
      properties:
        id:
          type: string
        name:
          type: string
        display_name:
          type: string
        status:
          type: string
          enum:
          - pending
          - active
          - suspended
        address:
          type: string
          format: email
          description: Primary address.
        addresses:
          type: array
          description: Every address, primary first (paid plans get the name on all domains).
          items:
            type: string
            format: email
        created_at:
          type: string
          format: date-time
    NameCheck:
      type: object
      required:
      - name
      - available
      - reason
      - short
      properties:
        name:
          type: string
        available:
          type: boolean
        reason:
          type: string
          description: Empty when available.
          enum:
          - ''
          - invalid
          - reserved
          - short_name_requires_paid_plan
          - taken
          - held
          - retired
        short:
          type: boolean
          description: 4 characters or fewer.
        message:
          type: string
        hint:
          type: string
    Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Stable machine-readable code, e.g. `not_found`, `name_taken`, `rate_limited`.
        message:
          type: string
        hint:
          type: string
          description: What to do next.
        details:
          type: object
          additionalProperties: true
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
  parameters:
    IdPath:
      name: id
      in: path
      required: true
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer <key>` with an API key (`bm_live_…`) or a

        pending claim key (`bm_pending_…`). OAuth 2.1 access tokens

        (`bm_oat_…`) are audience-bound to the MCP endpoint `/mcp` and are

        rejected on `/v1`; MCP clients discover OAuth via

        `/.well-known/oauth-protected-resource/mcp`.

        '
    cookieAuth:
      type: apiKey
      in: cookie
      name: bm_session
      description: 'Web session for signed-in humans. Non-GET requests must send a JSON

        `Content-Type` or `X-Botmail-CSRF: 1` (403 csrf otherwise).

        '