---
title: "List emails"
method: GET
path: "/api/emails/{address}/messages"
tags: ["Email"]
---

# List emails

`GET /api/emails/{address}/messages`

## Request

- Base URL: `https://domani.run`
- URL: `https://domani.run/api/emails/{address}/messages`
- Auth: HTTP bearer

List emails in a canonical folder or virtual view. Defaults to Inbox. Folder location is independent from message direction and spam verdict.

Authentication mail (OTPs / verification codes, password resets, magic links) is tagged `security: "auth"`. Tokens without the `email:auth_secrets` scope see those messages with subject and body REDACTED (`redacted: true`) - metadata (from, date) stays visible. The `subject`, `q` and `attachments` filters match what the caller may read: without the scope such a message matches only on its redacted subject and body, so a query for a code it holds finds nothing.

## Path parameters

- `address` string, required

## Query parameters

- `cursor` string
- `limit` integer
- `direction` 'in' | 'out' | 'all'
- `folder` 'inbox' | 'archive' | 'sent' | 'spam' | 'trash'
- `label` string
- `view` 'starred' | 'all' | 'needs_human' | 'scheduled'
- `since` string, date-time
- `until` string, date-time
- `from` string
- `to` string
- `subject` string
- `q` string
- `unread` boolean
- `attachments` boolean
- `spam` boolean

## Response `200`

Message list

- object
  - `messages` object[]
    - `id` string
    - `thread_id` string: Conversation id shared by every message of the thread (the root message id)
    - `labels` string[]: Every label on the message; `label` is the first one
    - `thread_key` string: Canonical backend-namespaced conversation key
    - `thread_aliases` string[]: Legacy workflow keys to pass back when mutating conversation state
    - `message_id` string, nullable
    - `direction` 'in' | 'out'
    - `folder` 'inbox' | 'archive' | 'sent' | 'spam' | 'trash'
    - `read` boolean
    - `starred` boolean
    - `needs_human` boolean: Flagged for a human (escalation)
    - `escalation_reason` string, nullable
    - `remind_at` string, nullable: Pending follow-up reminder time
    - `reminder_note` string, nullable
    - `answered` boolean
    - `forwarded` boolean
    - `spam_detected` boolean
    - `trashed_at` string, date-time, nullable
    - `from` string: The sender's display name and address from the From header (e.g. 'Alice <alice@example.com>'), or the bare address when the mail carried no name.
    - `avatar_url` string, uri, nullable: Privacy-preserving Domani proxy URL for the sender avatar
    - `to` string: Every To recipient from the header, with display names, in the order the sender wrote them (not only the envelope address that routed this mail to the mailbox).
    - `cc` string, nullable: Every Cc recipient from the header, with display names, or null when the mail carried no Cc.
    - `bcc` string, nullable: Bcc recipients, present only on your own outbound message (never on one you received, and never delivered as a header).
    - `reply_to` string, nullable
    - `subject` string
    - `text` string
    - `in_reply_to` string, nullable
    - `references` string, nullable
    - `status` string
    - `events` object[]
    - `created_at` string, date-time
  - `next_cursor` string, nullable

## Changes

- **2026-10-19** `7679f8159533`: 1 info
  - added the new enum value `scheduled` to the `query` request parameter `view`

[Operation history](https://skmtc.dev/domani/apis/domani-run-api/changes/api/emails/:address/messages/get.md)

---

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