---
title: "List Messages"
method: POST
path: "/messages/list"
tags: ["Messages"]
---

# List Messages

`POST /messages/list`

## Request

- Base URL: `https://api.pinnacle.sh`
- URL: `https://api.pinnacle.sh/messages/list`
- Auth: API key in header `PINNACLE-API-KEY`

List all messages with optional filtering and pagination. Results are sorted by creation date, newest first.

## Request body

- ListMessagesRequest
  - `pageIndex` integer
  - `pageSize` integer
  - `direction` 'INBOUND' | 'OUTBOUND'
  - `status` 'PENDING' | 'SENT' | 'SEND_FAILED' | 'DELIVERED' | 'DELIVERY_FAILED' | 'RECEIVED' | 'READ' | 'QUEUED' | 'FALLBACK_SENT'
  - `type` 'SMS' | 'MMS' | 'RCS'
  - `method` 'API' | 'SDK' | 'OTHER': Filter by the method used to send the message.
  - `from` string: Filter by sender phone number (E.164 format) or agent id.
  - `to` string: Filter by recipient phone number (E.164 format).
  - `content` string: Search message content (partial match, case-insensitive).
  - `dateFrom` string, date-time: Filter messages created on or after this date (ISO 8601 format).
  - `dateTo` string, date-time: Filter messages created on or before this date (ISO 8601 format).

## Response `200`

Returns paginated list of messages.

- ListMessagesResponse
  - `data` MessageSummary[], required
    - `id` string, required: Unique identifier for the message.
    - `status` 'PENDING' | 'SENT' | 'SEND_FAILED' | 'DELIVERED' | 'DELIVERY_FAILED' | 'RECEIVED' | 'READ' | 'QUEUED' | 'FALLBACK_SENT', required: Current status of the message.
    - `direction` 'INBOUND' | 'OUTBOUND', required: Direction of the message.
    - `type` 'SMS' | 'MMS' | 'RCS', required: Protocol type of the message.
    - `method` 'API' | 'SDK' | 'OTHER', required: Method used to send the message.
    - `numSegments` integer, required: Number of segments in the message.
    - `cost` number, double, nullable, required: Cost of the message.
    - `from` string, nullable, required: Sender phone number (E.164) or RCS agent ID.
    - `to` string, nullable, required: Recipient phone number in E.164 format.
    - `content` MessageSummaryContent, required: Message content (SMS text, MMS media, or RCS rich content).
    - `error` MessageSummaryError, required: Error details if the message failed.
    - `isTest` boolean, required: Whether this is a test message.
    - `blastId` string, nullable, required: ID of the blast this message belongs to, if any.
    - `sentAt` string, nullable, required: ISO 8601 timestamp of when the message was sent.
    - `deliveredAt` string, nullable, required: ISO 8601 timestamp of when the message was delivered.
    - `createdAt` string, required: ISO 8601 timestamp of when the message was created.
    - `updatedAt` string, required: ISO 8601 timestamp of when the message was last updated.
  - `hasMore` boolean, required
  - `count` integer, required

## Other responses

- `400`: Validation failed. The payload has missing required fields and/or invalid types. <br> See https://zod.dev/error-formatting for more information.
- `401`: The request lacks valid authentication credentials or the provided credentials are invalid. <br> Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.
- `500`: An unexpected error occurred on Pinnacle's servers while processing your request. <br> If this error persists, please contact support with the request details.

---

[API](https://skmtc.dev/pinnacle/apis/pinnacle-2.md) - [All operations](https://skmtc.dev/pinnacle/apis/pinnacle-2/llms.txt) - [OpenAPI document](https://skmtc.dev/pinnacle/apis/pinnacle-2/revisions/45416dadab79?raw)