---
title: "List all inbox messages for the account"
method: GET
path: "/v1/inbox"
tags: ["Inbox"]
---

# List all inbox messages for the account

`GET /v1/inbox`

## Request

- Base URL: `https://api.winnr.app`
- URL: `https://api.winnr.app/v1/inbox`
- Auth: HTTP bearer

Returns emails across every mailbox on the account, sorted by received
time descending, served from the DynamoDB cache. Supports cursor-based
pagination plus optional date-range, single-mailbox, and warmup-exclusion
filters applied server-side.

Pagination is cursor-based only. `page`, `offset` and `sort` are not
supported and are ignored: read `pagination.cursor` from the response
and pass it back as `cursor` to get the next page. `pagination` is
present on every 200 response.

When called with an API token, the first page of a read also kicks off
an inbox sync in the background (at most once every 10 minutes per
account), so a polling integration keeps seeing new mail without
calling POST /v1/inbox/refresh itself. The sync is asynchronous — new
messages land in the cache within a minute or two and appear on a
later poll, not in the response that triggered it. Requests that pass
a `cursor` never trigger a sync.

## Query parameters

- `limit` integer
- `cursor` string
- `date_from` string, date
- `date_to` string, date
- `mailbox` string
- `exclude_warmup` boolean
- `has_attachments` boolean

## Response `200`

Page of inbox messages

- InboxListResponse
  - `data` Email[]
    - `id` string
    - `uid` string: IMAP UID
    - `message_id` string: RFC 2822 Message-ID header (use for In-Reply-To when replying)
    - `thread_id` string: Thread identifier for grouping related messages
    - `from` string: Raw from header (may include display name)
    - `from_name` string: Sender display name
    - `from_email` string: Sender email address
    - `to` string
    - `cc` string
    - `bcc` string
    - `reply_to` string
    - `subject` string
    - `body` string: Full email body text
    - `body_preview` string: First 200 characters of the body
    - `received_at` string, date-time
    - `has_attachments` boolean
    - `is_read` boolean
    - `mailbox` string: Email address of the mailbox that received this message
  - `pagination` Pagination: Pagination metadata. Cursor-based endpoints (e.g. `/v1/domains`, `/v1/email-users`, `/v1/inbox`, `/v1/email-users/{id}/inbox`) populate `has_more` and `cursor`. Offset-based endpoints (e.g. `/v1/warming`) populate `page`, `per_page`, and `total`. `count` (number of items in the current page) is included where available.
    - `has_more` boolean: Whether more pages exist after this one (cursor-based endpoints).
    - `cursor` string, nullable: Opaque cursor to pass as `?cursor=…` for the next page.
    - `count` integer: Number of items returned in this response.
    - `total` integer: Total number of items across all pages (offset-based endpoints).
    - `page` integer: 1-based page number (offset-based endpoints).
    - `per_page` integer: Items per page (offset-based endpoints).
  - `meta` Meta
    - `request_id` string
    - `timestamp` string, date-time

## Other responses

- `401`: Authentication required or token invalid

---

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