# List message sync index for a label

Returns compact message records (UID, MODSEQ, flags, size, dates) ordered by UID for efficient folder synchronization (up to 10,000 per page).

## `GET /api/v1/mailboxes/{mailboxId}/labels/{label}/uids`

### Path parameters

- `mailboxId` (string, required) — Mailbox ULID identifier
- `label` (string, required) — Label or folder name (e.g. INBOX, Archive, custom)

### Query parameters

- `uidMin` (integer, ≥ 1) — Minimum UID inclusive
- `uidMax` (integer, ≥ 1) — Maximum UID inclusive
- `limit` (integer, ≥ 1, ≤ 10000) — Maximum items to return (default 1000, max 10000)
- `order` ("asc" | "desc") — UID order within the page (default asc). `desc` pages from the newest end, for a client that must keep the NEWEST N under a row cap.

### Responses

**200** — Message index page with UID validity

`application/json` → LabelUidPage

- `messages` (LabelUidEntry[], required) — List of message summaries ordered by UID
  - `blobHash` (string, required) — Storage blob SHA-256 hash
  - `flags` (string[], required) — System flags (seen, answered, flagged, draft, deleted)
  - `id` (string, required) — Message ULID
  - `keywords` (string[], required) — Custom keywords (e.g. $forwarded)
  - `modseq` (integer <int64>, required) — RFC 7162 MODSEQ change sequence number
  - `receivedAt` (integer <int64>, required) — Server receive timestamp in epoch seconds
  - `sentAt` (integer | null, required) — Sent timestamp from Date header in epoch seconds, or null
  - `size` (integer <int64>, required) — Message size in bytes
  - `uid` (integer <int64>, required) — Message UID inside this label
- `uidValidity` (integer <int64>, required) — UIDVALIDITY epoch of the label

**400** — validation_failed — malformed UID range or limit

`application/json` → ErrorOrValidation

**401** — unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge

`application/json` → ErrorBody

**404** — Mailbox or label not found

`application/json` → ErrorBody

**503** — temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)

`application/json` → ErrorBody

### Example request

```bash
curl -X GET 'https://api.open.email/api/v1/mailboxes/{mailboxId}/labels/{label}/uids' \
  -H 'Authorization: Bearer oek_…'
```

## TypeScript SDK

[`openemail.labels.listUids`](/docs/sdks/typescript/labels/list-uids)

```ts
const labelUidPage = await openemail.labels.listUids(mailboxId, label)
```
