# Search received messages

`GET /api/messages`

Returns the account's message history, newest first, 25 per page. Search q matches message ID, event ID, retained sender/recipient, subject and Message-ID. Supported status filters are returned by the API. Expired summaries hide message content.

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 are numbered from 1. Invalid input becomes 1 and excessive pages clamp to the final page.

```json
{
  "name": "page",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "default": 1
  },
  "description": "Pages are numbered from 1. Invalid input becomes 1 and excessive pages clamp to the final page."
}
```

### 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.

```json
{
  "name": "status",
  "in": "query",
  "schema": {
    "type": "string",
    "enum": [
      "pending",
      "processing",
      "parsed",
      "failed",
      "expired"
    ]
  }
}
```

## Responses

### 200

Success

Content type: `application/json`.

Schema:

```json
{
  "type": "object",
  "properties": {
    "messages": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/MessageSummary"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  },
  "required": [
    "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"
}
```

### 429



### 503



## Referenced schemas

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

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