# Retrieve messages from a named message box

> For the complete documentation index, see [llms.txt](https://bsvblockchain.com/docs/llms.txt).

**POST** `/listMessages`

Base URL: `https://{host}`

Returns one deterministic, bounded page of stored messages belonging
to the authenticated identity in the specified message box. Returns an
empty array if the box does not exist. Message bodies are always
returned as strings (JSON objects are stringified).

## Authorization

- x-bsv-auth-identity-key (apiKey in header)

## Body

Content type: `application/json`

- `messageBox` (string, required)
  Name of the message box to retrieve messages from.
- `limit` (integer)
- `offset` (integer)
- `skip` (integer)
  Compatibility alias for offset; both must match if supplied together.

Example:

```json
{
  "messageBox": "string",
  "limit": 1000,
  "offset": 0,
  "skip": 0
}
```

## Responses

### 200

Messages retrieved successfully (array may be empty).

- `status` ("success", required)
- `messages` (object[], required)
  - `messageId` (string)
  - `body` (string)
    Stringified message body (JSON objects are JSON.stringify-ed before storage).
  - `sender` (string)
    Compressed secp256k1 public key encoded as a 66-character hex string.
  - `createdAt` (string<date-time>)
  - `updatedAt` (string<date-time>)
- `limit` (integer, required)
- `offset` (integer, required)
- `nextOffset` (integer, required)
  Offset for the next page; unchanged when the result is empty.
- `hasMore` (boolean, required)

Example:

```json
{
  "status": "success",
  "messages": [
    {
      "messageId": "string",
      "body": "string",
      "sender": "string",
      "createdAt": "1970-01-01T00:00:00.000Z",
      "updatedAt": "1970-01-01T00:00:00.000Z"
    }
  ],
  "limit": 0,
  "offset": 0,
  "nextOffset": 0,
  "hasMore": true
}
```

### 400

Invalid or missing message box name.
Codes: `ERR_MESSAGEBOX_REQUIRED`, `ERR_INVALID_MESSAGEBOX`

- `status` ("error", required)
- `code` (string, required)
  Machine-readable error code (see specs/errors.md).
- `description` (string, required)
  Human-readable explanation.

Example:

```json
{
  "status": "error",
  "code": "string",
  "description": "string"
}
```

### 401

Authentication required.

- `status` ("error", required)
- `code` (string, required)
  Machine-readable error code (see specs/errors.md).
- `description` (string, required)
  Human-readable explanation.

Example:

```json
{
  "status": "error",
  "code": "string",
  "description": "string"
}
```

### 500

Internal server error (`ERR_INTERNAL_ERROR`).

- `status` ("error", required)
- `code` (string, required)
  Machine-readable error code (see specs/errors.md).
- `description` (string, required)
  Human-readable explanation.

Example:

```json
{
  "status": "error",
  "code": "string",
  "description": "string"
}
```