Coldrig Inbox API

openapi: 3.2.0
info:
  title: Coldrig Dev Inbox API
  version: 0.3.0
  contact:
    name: EpiphanyMade
    email: support@coldrig.dev
  license:
    name: MIT
  description: 'Operations tagged inbox across 2 of this provider''s published API definitions: coldrig-dev-openapi.yaml, coldrig-dev-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.coldrig.dev
  description: Production API host.
security:
- bearerAuth: []
tags:
- name: inbox
paths:
  /inbox:
    get:
      operationId: inbox
      tags:
      - inbox
      summary: Unified reply inbox across all mailboxes for the account
      description: 'v2: cursor-paginated, filterable. A bare GET /inbox (no query params) preserves the exact pre-v2 shape — every thread, bounces/OOO included, page 1 of 50.'
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      - name: cursor
        in: query
        schema:
          type: string
          minLength: 1
          maxLength: 500
      - name: mailbox
        in: query
        schema:
          type: string
          minLength: 1
          maxLength: 320
      - name: campaign
        in: query
        schema:
          type: string
          minLength: 1
          maxLength: 200
      - name: label
        in: query
        schema:
          type: string
          minLength: 1
          maxLength: 100
      - name: read
        in: query
        schema:
          type: boolean
      - name: include_nonreply
        in: query
        description: 'Include bounces/OOO/other non-reply threads. Default true (matches the pre-v2 GET /inbox shape); the dashboard UI''s default view sets this false.

          '
        schema:
          type: boolean
          default: true
      - name: archived
        in: query
        schema:
          type: string
          enum:
          - exclude
          - include
          - only
          default: exclude
      responses:
        '200':
          description: Inbox listing.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /threads/{id}:
    get:
      operationId: thread
      tags:
      - inbox
      summary: Full message history for one thread
      parameters:
      - $ref: '#/components/parameters/ThreadId'
      responses:
        '200':
          description: Thread detail.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /threads/{id}/reply:
    post:
      operationId: reply
      tags:
      - inbox
      summary: Send a reply on an existing thread
      parameters:
      - $ref: '#/components/parameters/ThreadId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplyInput'
      responses:
        '201':
          description: Reply sent (or a dedup replay — see `deduplicated` on the schema).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReplyResult'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: 'Reply refused by send governance, non-retryable: the recipient is suppressed, or the sending mailbox is deliverability-paused. Both need a state change before a retry can succeed.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
                    enum:
                    - send_blocked
                  reason:
                    type: string
                    enum:
                    - suppressed
                    - mailbox_paused
                    description: suppressed = recipient opted out or bounced; mailbox_paused = deliverability control loop paused this mailbox.
                  retryable:
                    type: boolean
                    enum:
                    - false
                required:
                - error
                - code
                - reason
                - retryable
        '429':
          description: 'Reply refused by send governance, retryable: the sending mailbox has used its full daily send allowance. Retry after the daily counter rolls over.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
                    enum:
                    - send_blocked
                  reason:
                    type: string
                    enum:
                    - daily_cap_reached
                    description: daily_cap_reached = the mailbox's warmup-ramp daily cap is used up for today.
                  retryable:
                    type: boolean
                    enum:
                    - true
                required:
                - error
                - code
                - reason
                - retryable
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /threads/{id}/mark:
    post:
      operationId: mark
      tags:
      - inbox
      summary: Mark a thread read, unread, or archived
      parameters:
      - $ref: '#/components/parameters/ThreadId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkInput'
      responses:
        '200':
          description: Marked.
          content:
            application/json:
              schema:
                type: object
                properties:
                  marked:
                    type: boolean
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /threads/{id}/label:
    post:
      operationId: label_thread
      tags:
      - inbox
      summary: Set (or, with label null, clear) a triage label on an inbox thread
      parameters:
      - $ref: '#/components/parameters/ThreadId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ThreadLabelInput'
      responses:
        '200':
          description: Label set/cleared.
          content:
            application/json:
              schema:
                type: object
                properties:
                  threadId:
                    type: string
                  label:
                    type:
                    - string
                    - 'null'
                  source:
                    type:
                    - string
                    - 'null'
                    enum:
                    - dashboard
                    - mcp
                    - api
                    - system
                    - null
                required:
                - threadId
                - label
                - source
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /activity:
    get:
      operationId: activity
      tags:
      - inbox
      summary: Unified, chronological feed of campaign events + deliverability control-loop…
      description: Merges the `events` table (sends/replies/bounces/complaints) with `deliverability_actions` (pause/throttle/rotate/replace-domain) into one cursor-paginated feed, one query.
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      - name: cursor
        in: query
        schema:
          type: string
          minLength: 1
          maxLength: 500
      - name: kind
        in: query
        description: Omit for every kind (backward-compatible default).
        schema:
          type: string
          enum:
          - event
          - deliverability
      responses:
        '200':
          description: Activity feed page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivityPage'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
components:
  schemas:
    MarkInput:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - read
          - unread
          - archived
    ReplyInput:
      type: object
      required:
      - body
      properties:
        body:
          type: string
          minLength: 1
          maxLength: 20000
    ActivityItem:
      type: object
      required:
      - id
      - kind
      - label
      - ts
      - target
      - detail
      properties:
        id:
          type: string
        kind:
          type: string
          enum:
          - event
          - deliverability
        label:
          type: string
        ts:
          type: integer
        target:
          type:
          - string
          - 'null'
        detail:
          type: object
          additionalProperties: true
    ReplyResult:
      type: object
      required:
      - messageId
      - deduplicated
      properties:
        messageId:
          type: string
        deduplicated:
          type: boolean
          description: 'true means NO new email was sent — `messageId` is from an earlier send this call matched, either the SAME Idempotency-Key at any time, or (when no key is supplied) an identical body sent within the last 10 minutes.


            false means this platform sent the call onward as a NEW send. That is normally a new email, but it is NOT a guarantee one left the building: without an Idempotency-Key the body hash is matched HERE for 10 minutes only, while the sending provider keeps its own record of an identical body on the same thread for longer and can collapse a much later repeat into the original send. On such a repeat you may receive false together with the ORIGINAL send''s messageId and no new email. Supply an Idempotency-Key, or vary the body, when a repeat must genuinely go out.

            '
    ThreadLabelInput:
      type: object
      properties:
        label:
          type:
          - string
          - 'null'
          minLength: 1
          maxLength: 100
          default: null
          description: Free-form (a UI-recommended taxonomy, not a server-enforced enum). null clears the label.
    ActivityPage:
      type: object
      required:
      - items
      - nextCursor
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ActivityItem'
        nextCursor:
          type:
          - string
          - 'null'
  responses:
    NotFound:
      description: Resource not found, or not owned by the authenticated account.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    ValidationError:
      description: Request body failed schema validation.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    Unauthorized:
      description: Missing, invalid, or inactive bearer token.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
  parameters:
    ThreadId:
      name: id
      in: path
      required: true
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Token returned by POST /signup. One token = one separate account. An app connected with "Sign in with Coldrig" (OAuth) holds its own short-lived token for the same account: it is accepted on the hosted MCP endpoint (/mcp) only, and on no REST route.

        '
    dashboardSessionCookie:
      type: apiKey
      in: cookie
      name: cs_dashboard_session
      description: 'httpOnly session cookie minted by POST /dashboard/session (30-day TTL). Alternative to bearerAuth for /dashboard/* routes only, used by the optional human dashboard SPA. A cookie-authed mutating request (any method other than GET/HEAD) must also send the `X-Coldstart-Client: dashboard` header (global CSRF guard) — bearer-authed requests are exempt.

        '
x-refined-from:
- coldrig-dev-openapi.yaml
- coldrig-dev-openapi.yml