# List retained threads

`GET /api/threads`

Lists account-scoped retained conversations, 25 groups per page, sorted by latest receipt descending with a stable ID tie-breaker. q and status match a retained member, including older members. Counts and latestMessage describe the complete retained thread. Search is a literal case-insensitive substring across sender, routed recipient, subject, Message-ID, receipt ID, event ID and thread ID. Combined filters must match the same member. Unthreaded messages appear individually with threadId null. Zero-day retention returns an empty list. Expired delivery audits are accessible through individual messages, not threads.

Send API requests to your Wildmail application origin. The documentation host does not serve API requests.

## Authentication

- apiKey: Send `Authorization: Bearer <token>` in the request headers. Wildmail scoped kmx_ API token.

- session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies.

Each bullet above is an alternative authentication method.

Required API key scope: `messages:read`.

Audience: management.

## Parameters

### page

query parameter; optional.

Pages start at 1. Invalid input becomes 1. Pages beyond the result set are empty.

```json
{
  "name": "page",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "default": 1
  },
  "description": "Pages start at 1. Invalid input becomes 1. Pages beyond the result set are empty."
}
```

### q

query parameter; optional.

Case-insensitive substring search.

```json
{
  "name": "q",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Case-insensitive substring search."
}
```

### status

query parameter; optional.

Match any retained member with this message status. parsed means complete. expired returns no threads.

```json
{
  "name": "status",
  "in": "query",
  "schema": {
    "type": "string",
    "enum": [
      "pending",
      "processing",
      "parsed",
      "failed",
      "expired"
    ]
  },
  "description": "Match any retained member with this message status. parsed means complete. expired returns no threads."
}
```

## Responses

### 200

Success

Content type: `application/json`.

Schema:

```json
{
  "type": "object",
  "properties": {
    "threads": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ThreadSummary"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    },
    "retentionDays": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    }
  },
  "required": [
    "threads",
    "pagination",
    "retentionDays"
  ]
}
```

### 401

Missing, invalid or revoked credentials.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 403

Required scope or account access missing.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 429



### 503



## Referenced schemas

References resolve against the [OpenAPI specification](/openapi.json).

### #/components/schemas/ThreadSummary

```json
{
  "type": "object",
  "description": "A complete retained thread, or a single retained message without thread metadata.",
  "properties": {
    "threadId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Untranslated conversation ID. Null means the latestMessage stands alone."
    },
    "latestMessage": {
      "$ref": "#/components/schemas/MessageSummary"
    },
    "messageCount": {
      "type": "integer",
      "minimum": 1
    },
    "firstReceivedAt": {
      "type": "string",
      "format": "date-time"
    },
    "latestReceivedAt": {
      "type": "string",
      "format": "date-time"
    },
    "statusCounts": {
      "type": "object",
      "properties": {
        "pending": {
          "type": "integer",
          "minimum": 0
        },
        "processing": {
          "type": "integer",
          "minimum": 0
        },
        "parsed": {
          "type": "integer",
          "minimum": 0
        },
        "failed": {
          "type": "integer",
          "minimum": 0
        }
      },
      "required": [
        "pending",
        "processing",
        "parsed",
        "failed"
      ],
      "description": "Message counts for the whole retained thread. Each message is counted once."
    }
  },
  "required": [
    "threadId",
    "latestMessage",
    "messageCount",
    "firstReceivedAt",
    "latestReceivedAt",
    "statusCounts"
  ]
}
```

### #/components/schemas/Pagination

```json
{
  "type": "object",
  "properties": {
    "page": {
      "type": "integer"
    },
    "pageCount": {
      "type": "integer"
    },
    "total": {
      "type": "integer"
    },
    "pageSize": {
      "type": "integer"
    }
  },
  "required": [
    "page",
    "pageCount",
    "total"
  ]
}
```

### #/components/schemas/Error

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "limit": {
      "type": "integer"
    }
  },
  "required": [
    "error"
  ]
}
```

### #/components/schemas/MessageSummary

```json
{
  "type": "object",
  "properties": {
    "receiptId": {
      "type": "string",
      "pattern": "^[a-f0-9]{24}$",
      "description": "Message identifier. Treat it as opaque."
    },
    "sender": {
      "type": [
        "string",
        "null"
      ]
    },
    "recipients": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "subject": {
      "type": [
        "string",
        "null"
      ]
    },
    "messageId": {
      "type": [
        "string",
        "null"
      ]
    },
    "processingStatus": {
      "type": "string",
      "enum": [
        "pending",
        "processing",
        "parsed",
        "failed",
        "expired"
      ]
    },
    "processingErrorCode": {
      "type": [
        "string",
        "null"
      ]
    },
    "processingError": {
      "type": [
        "string",
        "null"
      ]
    },
    "processingAttemptCount": {
      "type": "integer"
    },
    "processingNextRetryAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "receivedAt": {
      "type": "string",
      "format": "date-time"
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time"
    },
    "rawBytes": {
      "type": "integer"
    },
    "processedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "contentAvailable": {
      "type": "boolean"
    },
    "rawDownloadUrl": {
      "type": [
        "string",
        "null"
      ]
    },
    "threadId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Conversation ID, identical to message.thread_id in webhooks. Null for unavailable metadata or expired content. Treat as opaque."
    }
  },
  "required": [
    "receiptId",
    "sender",
    "recipients",
    "subject",
    "messageId",
    "processingStatus",
    "processingErrorCode",
    "processingError",
    "processingAttemptCount",
    "processingNextRetryAt",
    "receivedAt",
    "expiresAt",
    "rawBytes",
    "processedAt",
    "contentAvailable",
    "rawDownloadUrl",
    "threadId"
  ]
}
```
