> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hq.zone/llms.txt
> Use this file to discover all available pages before exploring further.

# List emails awaiting review

> Returns the three actionable email triage queues - awaiting-review, unrouted and
quarantined - each capped at 200 items, plus a count of each. The awaiting-review
queue is scoped to the caller (or all workspace mail for admins), while the unrouted
and quarantined queues are admin-only and come back empty with zero counts for a
non-admin caller.



## OpenAPI

````yaml GET /v1/api/email/review
openapi: 3.1.0
info:
  title: HQ API
  description: >-
    Public HTTP API for HQ. Authenticate with a Personal Access Token
    (`Authorization: Bearer hq_pat_...`) for server-side integrations, or an
    OAuth 2.1 authorization-code + PKCE flow for browser apps acting on a user's
    behalf. Both grant from the same resource:action scope vocabulary; an
    endpoint's required scope is listed under its `security`.
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  version: 1.0.0
servers:
  - url: https://api.hq.zone
    description: HQ API (production)
security: []
tags:
  - name: me
    description: The signed-in user's own account
  - name: conversations
    description: Conversations and their messages
  - name: documents
    description: The content-addressed documents library
  - name: schedules
    description: Scheduled prompts and recurring tasks
  - name: agents
    description: Agents, their skills and integrations
  - name: memory
    description: What the assistant remembers (L5 governance)
  - name: tokens
    description: Personal Access Token management
  - name: billing
    description: Usage and billing
  - name: notifications
    description: In-app notification center
  - name: admin
    description: Workspace administration
  - name: integrations
    description: Workspace integrations (Slack, MCP, skills)
  - name: onboarding
    description: New-workspace onboarding wizard
  - name: auth
    description: Sign-in, sessions, and OAuth
paths:
  /v1/api/email/review:
    get:
      tags:
        - admin
      summary: List emails awaiting review
      description: >-
        Returns the three actionable email triage queues - awaiting-review,
        unrouted and

        quarantined - each capped at 200 items, plus a count of each. The
        awaiting-review

        queue is scoped to the caller (or all workspace mail for admins), while
        the unrouted

        and quarantined queues are admin-only and come back empty with zero
        counts for a

        non-admin caller.
      operationId: list_review
      responses:
        '200':
          description: The three actionable triage queues + counts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReviewQueues'
      security:
        - bearer_pat:
            - conversations:read
        - oauth2:
            - conversations:read
components:
  schemas:
    ReviewQueues:
      type: object
      required:
        - awaiting_review
        - unrouted
        - quarantined
        - review_reply
        - counts
      properties:
        awaiting_review:
          type: array
          items:
            $ref: '#/components/schemas/ActivityRow'
        counts:
          $ref: '#/components/schemas/ReviewCounts'
        quarantined:
          type: array
          items:
            $ref: '#/components/schemas/QuarantineRow'
          description: Admin-only; empty for a non-admin caller.
        review_reply:
          type: array
          items:
            $ref: '#/components/schemas/ActivityRow'
          description: >-
            Replies to the team / default sender. A user sees items attributed
            to

            them; an admin sees all, incl. the Unassigned bucket
            (review_owner_id

            is null). Never re-injected into agent context.
        unrouted:
          type: array
          items:
            $ref: '#/components/schemas/ActivityRow'
          description: Admin-only; empty for a non-admin caller.
    ActivityRow:
      type: object
      description: |-
        One row of the Activity feed: an inbound or outbound `email_message`,
        decorated with its endpoint + plane and a deep-link to the conversation
        thread (so opening it reuses the shared conversation renderer).
      required:
        - email_message_id
        - direction
        - handling_state
        - from_addr
        - to_addrs
        - occurred_at
      properties:
        agent_id:
          type:
            - string
            - 'null'
          format: uuid
        conversation_id:
          type:
            - string
            - 'null'
          format: uuid
          description: |-
            The conversation thread this mail belongs to (channel_kind='email',
            channel_thread=thread_key). `None` only for a parked item whose
            conversation was never materialised (unrouted / filed).
        direction:
          type: string
        email_message_id:
          type: string
          format: uuid
        endpoint_id:
          type:
            - string
            - 'null'
          format: uuid
        endpoint_localpart:
          type:
            - string
            - 'null'
        endpoint_plane:
          type:
            - string
            - 'null'
        from_addr:
          type: string
        handling_state:
          type: string
        llm_category:
          type:
            - string
            - 'null'
        llm_summary:
          type:
            - string
            - 'null'
        occurred_at:
          type: string
          format: date-time
        review_owner_id:
          type:
            - string
            - 'null'
          format: uuid
          description: |-
            The HQ user this `review_reply` item is attributed to; `null` = the
            admin Unassigned bucket. Only meaningful on the review_reply queue.
        subject:
          type:
            - string
            - 'null'
        to_addrs:
          type: array
          items:
            type: string
    ReviewCounts:
      type: object
      required:
        - awaiting_review
        - unrouted
        - quarantined
        - review_reply
      properties:
        awaiting_review:
          type: integer
          format: int64
        quarantined:
          type: integer
          format: int64
        review_reply:
          type: integer
          format: int64
          description: >-
            Replies to the team / default sender awaiting human review. Scoped
            to

            the caller (own attributed items); admins also see the Unassigned
            ones.
        unrouted:
          type: integer
          format: int64
    QuarantineRow:
      type: object
      required:
        - id
        - from_addr
        - to_addr
        - reason
        - sentio_message_id
        - created_at
      properties:
        created_at:
          type: string
          format: date-time
        from_addr:
          type: string
        id:
          type: string
          format: uuid
        llm_category:
          type:
            - string
            - 'null'
        llm_summary:
          type:
            - string
            - 'null'
        reason:
          type: string
        sentio_message_id:
          type: string
          format: uuid
        to_addr:
          type: string
  securitySchemes:
    bearer_pat:
      type: http
      scheme: bearer
      bearerFormat: hq_pat
      description: 'Personal Access Token. Send as `Authorization: Bearer hq_pat_...`.'
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.hq.zone/v1/oauth/authorize
          tokenUrl: https://api.hq.zone/v1/oauth/token
          refreshUrl: https://api.hq.zone/v1/oauth/token
          scopes:
            admin: Administer the workspace (users, settings, integrations)
            agents:read: View the agents in your workspace
            agents:write: Create and configure agents
            billing:read: View usage and billing information
            conversations:read: Read your conversations and their messages
            conversations:write: Start conversations and send messages on your behalf
            documents:read: Read your documents library
            documents:write: Upload and manage documents in your library
            memory:read: Read what the assistant remembers about you
            memory:write: Correct or delete what the assistant remembers
            schedules:read: View your scheduled tasks
            schedules:write: Create and manage scheduled tasks
            tables:read: Read your tables and their rows
            tables:write: Create tables and add, edit, or delete rows

````