Botmail Events API

openapi: 3.2.0
info:
  title: Botmail Events 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: Events
  description: Per-mailbox event stream (long-poll).
paths:
  /v1/events:
    get:
      tags:
      - Events
      operationId: listEvents
      summary: Long-poll mailbox events
      description: 'Scope: read. Pending claim keys allowed. Without `after`, returns

        `{events: [], next_after: }` immediately so you can start

        tailing. Then pass `next_after` back as `after`; with `wait` the call

        blocks up to that many seconds until an event arrives.'
      parameters:
      - $ref: '#/components/parameters/MailboxIdQuery'
      - name: after
        in: query
        description: Return events with `seq` greater than this.
        schema:
          type: integer
          format: int64
          minimum: 0
      - name: wait
        in: query
        description: Seconds to wait for new events when none are ready.
        schema:
          type: integer
          minimum: 0
          maximum: 30
          default: 0
      - name: types
        in: query
        description: Comma-separated event types to include.
        schema:
          type: string
        example: message.received,message.status
      responses:
        '200':
          description: Events, oldest first.
          content:
            application/json:
              schema:
                type: object
                required:
                - events
                - next_after
                properties:
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                  next_after:
                    type: integer
                    format: int64
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    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
    EventType:
      type: string
      enum:
      - message.received
      - message.sent
      - message.status
      - thread.updated
      - mailbox.claimed
    Event:
      type: object
      required:
      - seq
      - mailbox_id
      - type
      - created_at
      properties:
        seq:
          type: integer
          format: int64
          description: Increasing sequence; use as `after`.
        mailbox_id:
          type: string
        type:
          $ref: '#/components/schemas/EventType'
        thread_id:
          type: string
        message_id:
          type: string
        data:
          type: object
          additionalProperties: true
          description: 'Type-specific. message.received: `{from, subject, status}`.

            message.status: `{status, reason?}` where status is delivered,

            bounced, complained, blocked, held, failed or sent.

            '
        created_at:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
  responses:
    BadRequest:
      description: Invalid request (`bad_request` or a more specific code).
      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'
    NotFound:
      description: Not found or not accessible with this credential.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    MailboxIdQuery:
      name: mailbox_id
      in: query
      description: Limit to one mailbox. Omit for every mailbox the credential can access.
      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).

        '