Coldrig Compliance API

openapi: 3.2.0
info:
  title: Coldrig Dev Compliance API
  version: 0.3.0
  contact:
    name: EpiphanyMade
    email: support@coldrig.dev
  license:
    name: MIT
  description: 'Operations tagged compliance 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: Compliance
paths:
  /unsubscribe:
    get:
      operationId: unsubscribe_confirm_page
      tags:
      - Compliance
      summary: Render a human confirm page for the in-body one-click unsubscribe link
      description: UNAUTHENTICATED — the signed `tenant`/`email`/`sig` triplet in the query string (minted server-side into every sequence email's List-Unsubscribe header and in-body opt-out link) is the credential; there is no bearer token on this route. GET alone never suppresses anything — it renders an HTML confirm page whose own form POSTs back to this same URL. Intended for a human clicking the link inside the email body, in a browser; a mail client's own automatic RFC 8058 one-click action POSTs directly (see below) and never hits this GET.
      security: []
      parameters:
      - $ref: '#/components/parameters/UnsubscribeTenant'
      - $ref: '#/components/parameters/UnsubscribeEmail'
      - $ref: '#/components/parameters/UnsubscribeSig'
      responses:
        '200':
          description: Confirm page (not yet unsubscribed).
          content:
            text/html:
              schema:
                type: string
        '400':
          description: Missing/invalid query params or an invalid/tampered signature.
          content:
            text/html:
              schema:
                type: string
    post:
      operationId: unsubscribe_confirm
      tags:
      - Compliance
      summary: Perform the RFC 8058 one-click unsubscribe (or confirm from the GET page)
      description: 'UNAUTHENTICATED, same credential as the GET above. This is the exact URL a compliant mail client POSTs to automatically for its own native "Unsubscribe" action (`List-Unsubscribe-Post: List-Unsubscribe=One-Click`) — no human interaction on this page in that flow — and is also what the GET confirm page''s own form submits to when a human clicks through the in-body link instead. Suppresses the address account-wide immediately (visible to the very next scheduling tick, not a CAN-SPAM- style grace window) and cancels every pending scheduled send for every lead sharing that email across every campaign. Idempotent: a repeat call with the same valid token always 200s.'
      security: []
      parameters:
      - $ref: '#/components/parameters/UnsubscribeTenant'
      - $ref: '#/components/parameters/UnsubscribeEmail'
      - $ref: '#/components/parameters/UnsubscribeSig'
      responses:
        '200':
          description: Unsubscribed (or already was — idempotent).
          content:
            text/html:
              schema:
                type: string
        '400':
          description: Missing/invalid query params or an invalid/tampered signature — no suppression applied.
          content:
            text/html:
              schema:
                type: string
        '413':
          description: Request body too large.
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
components:
  parameters:
    UnsubscribeSig:
      name: sig
      in: query
      required: true
      description: 'HMAC-SHA256 over `tenant:email`, keyed off a server secret. There is no per-send row backing this — the signature itself is the entire credential, and it never expires (an opt-out doesn''t need to).

        '
      schema:
        type: string
        minLength: 1
        maxLength: 128
    UnsubscribeTenant:
      name: tenant
      in: query
      required: true
      description: The account id this signed opt-out link belongs to.
      schema:
        type: string
        minLength: 1
        maxLength: 200
    UnsubscribeEmail:
      name: email
      in: query
      required: true
      description: The recipient address this signed opt-out link covers.
      schema:
        type: string
        minLength: 1
        maxLength: 320
        format: email
  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