# Inspect a retained thread

`GET /api/threads/{id}`

Returns the complete retained thread summary and its message summaries, oldest receipt first with a stable message ID tie-breaker, 25 messages per page. Current retention applies to both counts and members. Unknown, foreign-account, fully expired and zero-day threads return 404. IDs are the threadId values from message and thread summaries. Each message links to existing preview, raw download, attachment and delivery APIs.

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

### id

path parameter; required.

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[a-f0-9]{24}$"
  }
}
```

### 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."
}
```

## Responses

### 200

Success

Content type: `application/json`.

Schema:

```json
{
  "type": "object",
  "properties": {
    "thread": {
      "$ref": "#/components/schemas/ThreadSummary"
    },
    "messages": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/MessageSummary"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  },
  "required": [
    "thread",
    "messages",
    "pagination"
  ]
}
```

### 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"
}
```

### 404

Thread not found, outside this account, or without retained messages.

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/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"
  ]
}
```

### #/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"
  ]
}
```
