---
title: "List messages across inboxes"
method: GET
path: "/v1/messages"
tags: ["Messages"]
---

# List messages across inboxes

`GET /v1/messages`

## Request

- Base URL: `https://anjal.app`
- URL: `https://anjal.app/v1/messages`
- Auth: API key in header `X-API-Key`

One list across every inbox the key can see (tenant, workspace, inbox or
teammate scope). `?labels=a,b` returns messages carrying every label;
with `group=thread` it matches whole threads (a thread matches when any
of its messages carries the labels) and each row carries the thread's
`labels`.

## Query parameters

- `folder` 'inbox' | 'sent' | 'starred' | 'archived' | 'spam' | 'trash'
- `group` 'thread'
- `inboxId` string, uuid
- `labels` string
- `limit` integer
- `offset` integer

## Response `200`

OK

- object
  - `messages` Message[]
    - `id` string, uuid
    - `direction` 'inbound' | 'outbound'
    - `from` string
    - `to` string
    - `subject` string
    - `plainBody` string, nullable
    - `htmlBody` string, nullable
    - `isRead` boolean
    - `threadId` string, uuid, nullable
    - `messageIdHeader` string, nullable
    - `inReplyTo` string, nullable
    - `receivedAt` string, date-time
    - `labels` string[]: Lowercase labels on this message.
    - `isSpam` boolean: Flagged by the spam filter. Spam is left out of lists unless `includeSpam=true`.
    - `deliveryStatus` 'delivered' | 'bounced' | 'complained' | 'rejected' | 'null', nullable: Outbound only. `delivered` means the recipient's mail server accepted it (not a guarantee of inbox placement). Null until known.
    - `deliveredAt` string, date-time, nullable: When the recipient's mail server accepted the message (outbound only).
    - `firstOpenedAt` string, date-time, nullable: Time of the first open (outbound sends with `trackOpens: true` only). NULL until the first open. Opens are a hint, not proof: Apple Mail Privacy Protection fetches images on delivery, and clients that block images never report an open.
    - `lastOpenedAt` string, date-time, nullable: Most recent open event. Updates on every open.
    - `openCount` integer: Total opens. Subject to the same caveats as the timestamps.
    - `firstClickedAt` string, date-time, nullable: Timestamp of the first recipient link-click. Reliable signal of engagement (unlike opens, click events are not Apple-MPP-poisoned). NULL until the first click.
    - `lastClickedAt` string, date-time, nullable
    - `clickCount` integer
    - `attachments` AttachmentMeta[]
      - `id` string, uuid
      - `filename` string
      - `contentType` string
      - `sizeBytes` integer
      - `inline` boolean: Present and true when `htmlBody` embedded this attachment as an inline image and `?inlineImages=refs` replaced it with `attachment:<id>`.

---

[API](https://skmtc.dev/anjal/apis/anjal-api.md) · [All operations](https://skmtc.dev/anjal/apis/anjal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/anjal/apis/anjal-api/revisions/a4044778e294?raw)