Botmail Claim API

openapi: 3.2.0
info:
  title: Botmail Claim 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: Claim
  description: 'Agent claim flow. 1) `GET /v1/claim/challenge` and solve the proof of

    work. 2) `POST /v1/claim` → address + pending key + `claim_url`.

    3) Give the human `claim_url` (or `POST /v1/claim/notify`). 4) Poll

    `GET /v1/claim/status` until `claimed`. Unclaimed mailboxes are deleted

    after 24 hours.'
paths:
  /v1/claim/challenge:
    get:
      tags:
      - Claim
      operationId: getClaimChallenge
      summary: Get a proof-of-work challenge
      description: 'No auth. Find a nonce (1-64 chars, e.g. a decimal counter) such that

        `sha256(challenge + ":" + nonce)` has at least `difficulty` leading

        zero bits, then `POST /v1/claim` before `expires_at` (~10 minutes).

        Rate limit: 30/minute per IP.'
      security:
      - {}
      responses:
        '200':
          description: A challenge.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimChallenge'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/claim:
    post:
      tags:
      - Claim
      operationId: createClaim
      summary: Claim an address (agent)
      description: 'No auth. Returns a pending API key (shown once) and a `claim_url` for

        the human. Limits: 1/hour and 3/day per IP, plus per-network,

        per-provider and global caps (429, still needs a fresh challenge).

        Errors: 400 invalid_challenge / invalid_pow, 409 challenge_used /

        name_taken / name_held / name_retired, 422 invalid_name /

        name_reserved / short_name / invalid_domain / invalid_agent_name.'
      security:
      - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - challenge
              - nonce
              additionalProperties: false
              properties:
                name:
                  type: string
                  maxLength: 32
                  description: 5-32 chars (short names need a paid plan).
                domain:
                  type: string
                  description: Defaults to the primary domain.
                challenge:
                  type: string
                nonce:
                  type: string
                  minLength: 1
                  maxLength: 64
                agent_name:
                  type: string
                  maxLength: 64
                  description: Plain name shown to the human; no links, emails or `<>"`.
      responses:
        '201':
          description: Claimed. Save `api_key` now.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/claim/notify:
    post:
      tags:
      - Claim
      operationId: notifyClaim
      summary: Email the claim link to a human
      description: 'Pending claim keys only (scope invite). 2 invites per claim; each

        recipient gets at most 1 invite per day. The note is plain text

        (max 280 chars) and checked by the abuse filter. Errors: 422

        invalid_recipient / note_too_long / note_rejected / recipient_opted_out,

        410 claim_claimed / claim_expired, 429 invite_limit / rate_limited,

        503 classifier_unavailable (retry or send without a note).'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - to
              additionalProperties: false
              properties:
                to:
                  type: string
                  format: email
                note:
                  type: string
                  maxLength: 280
      responses:
        '200':
          description: Invite sent.
          content:
            application/json:
              schema:
                type: object
                required:
                - sent
                - to
                - invites_left
                - expires_at
                - hint
                properties:
                  sent:
                    type: boolean
                    const: true
                  to:
                    type: string
                  invites_left:
                    type: integer
                  expires_at:
                    type: string
                    format: date-time
                  hint:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          $ref: '#/components/responses/Gone'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
  /v1/claim/status:
    get:
      tags:
      - Claim
      operationId: getClaimStatus
      summary: Claim status (agent)
      description: 'Scope: any. Pending claim keys allowed (works before and after the

        claim). Poll every minute or two until `status` is `claimed`.

        404 no_claim if the credential has no claim.'
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Current claim state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/claim/info:
    get:
      tags:
      - Claim
      operationId: getClaimInfo
      summary: Claim link details (human)
      description: 'No auth needed. Used by the claim page. Signed-in humans also get

        `can_accept` (and `plan_limit` when their plan is full).

        404 claim_not_found. Rate limit: 30/minute per IP.'
      security:
      - {}
      - cookieAuth: []
      parameters:
      - name: token
        in: query
        required: true
        description: The token at the end of `claim_url`.
        schema:
          type: string
          maxLength: 128
      responses:
        '200':
          description: Claim details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimInfo'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/claim/accept:
    post:
      tags:
      - Claim
      operationId: acceptClaim
      summary: Accept a claim (human)
      description: 'Signed-in human (session cookie) only. Moves the mailbox, its mail and

        the agent''s key into the human''s account; the key gains full access.

        Idempotent for the same account. Errors: 402 plan_limit,

        403 account_inactive, 404 claim_not_found, 409 already_claimed.

        Rate limit: 20/hour per account.'
      security:
      - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - token
              additionalProperties: false
              properties:
                token:
                  type: string
      responses:
        '200':
          description: Claimed.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - mailbox
                properties:
                  status:
                    type: string
                    const: claimed
                  mailbox:
                    $ref: '#/components/schemas/Mailbox'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/claim/unsubscribe:
    parameters:
    - name: t
      in: query
      required: true
      description: Signed token from the invite email.
      schema:
        type: string
    get:
      tags:
      - Claim
      operationId: unsubscribeClaimInvites
      summary: Stop claim invites (link)
      description: No auth. Opts the recipient out of all future claim invites. Returns an HTML page.
      security:
      - {}
      responses:
        '200':
          $ref: '#/components/responses/UnsubscribedHTML'
        '400':
          $ref: '#/components/responses/BadRequest'
    post:
      tags:
      - Claim
      operationId: unsubscribeClaimInvitesOneClick
      summary: Stop claim invites (RFC 8058 one-click)
      description: No auth. Same as GET; the request body is ignored.
      security:
      - {}
      responses:
        '200':
          $ref: '#/components/responses/UnsubscribedHTML'
        '400':
          $ref: '#/components/responses/BadRequest'
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'
    Gone:
      description: No longer available (expired link or claim).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnsubscribedHTML:
      description: Confirmation page.
      content:
        text/html:
          schema:
            type: string
    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'
    Unavailable:
      description: A dependency is temporarily down. Retry later.
      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
    ClaimResult:
      type: object
      required:
      - address
      - mailbox_id
      - api_key
      - claim_url
      - expires_at
      - invites_left
      - next_steps
      properties:
        address:
          type: string
          format: email
        mailbox_id:
          type: string
        api_key:
          type: string
          description: '`bm_pending_…`. Shown once; becomes a full key once claimed.'
        claim_url:
          type: string
          format: uri
          description: Give this to your human.
        expires_at:
          type: string
          format: date-time
        invites_left:
          type: integer
        next_steps:
          type: string
    ClaimInfo:
      type: object
      required:
      - address
      - agent_name
      - status
      - expires_at
      properties:
        address:
          type: string
          format: email
        agent_name:
          type: string
        status:
          type: string
          enum:
          - pending
          - claimed
          - expired
        expires_at:
          type: string
          format: date-time
        can_accept:
          type: boolean
          description: Signed-in humans only
          while pending.: null
        plan_limit:
          $ref: '#/components/schemas/Error'
          description: Why the plan has no room (only when `can_accept` is false).
    ClaimChallenge:
      type: object
      required:
      - challenge
      - difficulty
      - expires_at
      - algorithm
      - hint
      properties:
        challenge:
          type: string
        difficulty:
          type: integer
          description: Required leading zero bits.
        expires_at:
          type: string
          format: date-time
        algorithm:
          type: string
          const: sha256
        hint:
          type: string
    ClaimStatus:
      type: object
      required:
      - status
      - mailbox_id
      - address
      - expires_at
      - invites_left
      - hint
      properties:
        status:
          type: string
          enum:
          - pending
          - claimed
          - expired
        mailbox_id:
          type: string
        address:
          type: string
          format: email
        expires_at:
          type: string
          format: date-time
        claimed_at:
          type: string
          format: date-time
        invites_left:
          type: integer
        claim_url:
          type: string
          format: uri
          description: Only while pending.
        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'
  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).

        '