## List messages

`GET /get-messages-api`

Returns a paginated list of the authenticated user's messages — outbound and inbound merged into a single feed. Each message includes a durable `message_handle` that can be passed to `/get-message-api/:message_handle` for the full record.

### Query parameters

- `limit` (integer (1–100)) — Maximum number of messages to return. Defaults to 100.

- `offset` (integer (≥ 0)) — Pagination offset. Defaults to 0. offset + limit must be ≤ 2000; deeper pages return 400 regardless of limit.

- `order_by` ("createdAt" | "sentAt") — Sort field. Defaults to createdAt.

- `order_direction` ("asc" | "desc") — Sort direction. Defaults to desc (newest first).

- `service` ("iMessage" | "SMS" | "RCS") — Filter by delivery service. Note: RCS is inbound-only — combining service=RCS with direction=outbound returns zero results.

- `direction` ("inbound" | "outbound") — Filter to inbound or outbound only. Omit for both.

- `pb_line_id` (string) — Encoded Project Blue line id (from GET /get-lines). The only supported way to filter by one of your own PB lines — do not use from_number/to_number for that.

- `from_number` (string (E.164)) — External sender. Inbound-only filter. Combining with direction=outbound returns 400.

- `to_number` (string (E.164)) — External recipient. Outbound-only filter. Combining with direction=inbound returns 400.

- `created_at_gte` (string (ISO-8601)) — Lower bound on created_at.

- `created_at_lte` (string (ISO-8601)) — Upper bound on created_at.

- `sent_at_gte` (string (ISO-8601)) — Lower bound on sent_at.

- `sent_at_lte` (string (ISO-8601)) — Upper bound on sent_at.

> **Group messages and from_number / to_number**
>
> On outbound group messages, `to_number` is the group's chat identifier (`chat…`), not an E.164 number. On inbound group messages, `from_number` is the individual participant who replied. The `to_number` and `from_number` filters are therefore not a way to fetch a group thread.There is currently no supported filter for reading one group thread from `/get-messages-api`. The `pbg_` groupId is not accepted as a filter, and the chat identifier is not exposed as a queryable field on this API.

> **About message_handle**
>
> The `message_handle` is an opaque, user-scoped identifier. Don't try to parse or decode it — just hand it back to `/get-message-api` to look up that specific message.

**Request — cURL**

```bash
curl -G https://api.tryprojectblue.com/get-messages-api \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "limit=5" \
  --data-urlencode "direction=outbound" \
  --data-urlencode "service=SMS"
```

**Response — 200 OK**

```json
{
  "status": "OK",
  "data": [
    {
      "message_handle": "pbm_outk6dawyUgbl-EjXCZk-g5mZnmwmSbilbaX-fvceChASMVXv1v26ONS0XENe2ggdJ82j9TMpw",
      "content": "Hello this is a message from desktop Claude!",
      "from_number": "+14804328406",
      "to_number": "+14808405291",
      "line_id": "7fd53c9a-5e6f-40e7-48c2-57663bad6c9c",
      "service": "SMS",
      "direction": "outbound",
      "status": "delivered",
      "created_at": "2026-04-19T07:30:14.525Z",
      "sent_at": "2026-04-19T16:00:31.091Z",
      "media_attachment_url": null,
      "voice_attachment_url": null
    }
  ],
  "pagination": { "limit": 100, "offset": 0, "total": 427 }
}
```

**Response — 400 — filter**

```json
{
  "error": "to_number only applies to outbound messages. Use pb_line_id to filter inbound messages by your own line."
}
```

**Response — 400 — depth**

offset + limit may not exceed 2000.

```json
{
  "error": "Pagination depth too deep. offset+limit must be <= 2000"
}
```