Botmail Billing API

openapi: 3.2.0
info:
  title: Botmail Billing 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: Billing
  description: Plans, checkout and the billing portal. Changes need a signed-in human.
paths:
  /v1/account/usage:
    get:
      tags:
      - Billing
      operationId: getUsage
      summary: Plan, storage and send allowance
      description: 'Scope: any. Pending claim keys allowed.'
      responses:
        '200':
          description: Usage and limits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/billing/plans:
    get:
      tags:
      - Billing
      operationId: listPlans
      summary: Plans and limits
      description: No auth.
      security:
      - {}
      responses:
        '200':
          description: Every plan and the storage add-on.
          content:
            application/json:
              schema:
                type: object
                required:
                - plans
                - storage_addon
                properties:
                  plans:
                    type: array
                    items:
                      $ref: '#/components/schemas/Limits'
                  storage_addon:
                    type: object
                    required:
                    - id
                    - price_usd
                    - storage_bytes
                    properties:
                      id:
                        type: string
                        const: storage_10gb
                      price_usd:
                        type: integer
                      storage_bytes:
                        type: integer
                        format: int64
  /v1/billing/checkout:
    post:
      tags:
      - Billing
      operationId: createCheckout
      summary: Start a checkout
      description: 'Signed-in human only (agents get 403 with a link to give their human).

        Errors: 400 unknown_plan / addon_not_available, 409 already_on_plan,

        402 payment_required.'
      security:
      - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - plan
              additionalProperties: false
              properties:
                plan:
                  type: string
                  enum:
                  - free
                  - pro
                  - team
                  - scale
                  - storage_10gb
                success_path:
                  type: string
                  description: Same-origin path to return to. Default `/settings/billing?checkout=success`.
      responses:
        '200':
          $ref: '#/components/responses/RedirectURL'
        '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'
  /v1/billing/portal:
    post:
      tags:
      - Billing
      operationId: createPortalSession
      summary: Open the billing portal
      description: Signed-in human only. Body optional.
      security:
      - cookieAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                return_path:
                  type: string
                  description: Same-origin path. Default `/settings/billing`.
      responses:
        '200':
          $ref: '#/components/responses/RedirectURL'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v1/billing/sync:
    post:
      tags:
      - Billing
      operationId: syncBilling
      summary: Refresh the plan from the billing provider
      description: Signed-in human only. Call after returning from checkout.
      security:
      - cookieAuth: []
      responses:
        '200':
          description: Current plan and storage.
          content:
            application/json:
              schema:
                type: object
                required:
                - plan
                - extra_storage_bytes
                - quota_bytes
                properties:
                  plan:
                    $ref: '#/components/schemas/Plan'
                  extra_storage_bytes:
                    type: integer
                    format: int64
                  quota_bytes:
                    type: integer
                    format: int64
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  responses:
    Conflict:
      description: Conflicts with current state.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RedirectURL:
      description: Open `url` in the browser.
      content:
        application/json:
          schema:
            type: object
            required:
            - url
            properties:
              url:
                type: string
                format: uri
    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'
    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'
  schemas:
    Usage:
      type: object
      required:
      - plan
      - kind
      - status
      - limits
      - used_bytes
      - quota_bytes
      - extra_storage_bytes
      - over_quota
      - mailboxes
      properties:
        plan:
          $ref: '#/components/schemas/Plan'
        kind:
          type: string
          enum:
          - human
          - pending
        status:
          type: string
          enum:
          - active
          - receive_only
          - suspended
          - deleting
        limits:
          $ref: '#/components/schemas/Limits'
        used_bytes:
          type: integer
          format: int64
        quota_bytes:
          type: integer
          format: int64
        extra_storage_bytes:
          type: integer
          format: int64
        over_quota:
          type: boolean
          description: New mail is held while true.
        mailboxes:
          type: object
          required:
          - used
          - limit
          properties:
            used:
              type: integer
            limit:
              type: integer
        sends_today:
          $ref: '#/components/schemas/Allowance'
          description: Omitted if the allowance lookup fails.
    Limits:
      type: object
      required:
      - plan
      - price_usd
      - mailboxes
      - storage_bytes
      - all_domains
      - short_names
      - start_new_recipients
      - max_new_recipients
      - max_total_per_day
      - custom_domains
      - storage_addon_allowed
      properties:
        plan:
          $ref: '#/components/schemas/Plan'
        price_usd:
          type: integer
          description: Per month.
        mailboxes:
          type: integer
        storage_bytes:
          type: integer
          format: int64
        all_domains:
          type: boolean
          description: Same name on every Botmail domain.
        short_names:
          type: boolean
          description: Names of 4 characters or fewer.
        start_new_recipients:
          type: integer
          description: New recipients per day at the starting trust level.
        max_new_recipients:
          type: integer
          description: Plan ceiling for new recipients per day.
        max_total_per_day:
          type: integer
        custom_domains:
          type: integer
        storage_addon_allowed:
          type: boolean
    Plan:
      type: string
      enum:
      - free
      - pro
      - team
      - scale
    Allowance:
      type: object
      required:
      - level
      - new_recipients_per_day
      - total_per_day
      - new_recipients_used
      - total_used
      properties:
        level:
          type: integer
          description: Trust level 0-3.
        new_recipients_per_day:
          type: integer
        total_per_day:
          type: integer
        new_recipients_used:
          type: integer
        total_used:
          type: integer
    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'
  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).

        '