---
title: "Search one mailbox by meaning and by words"
method: GET
path: "/api/emails/{address}/search"
tags: ["Email"]
---

# Search one mailbox by meaning and by words

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

## Request

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

The same search as `GET /api/emails/search`, restricted to this mailbox. Requires `email:read`. Without `email:auth_secrets`, inbound authentication mail is left out before ranking: no word, operator or filter matches it, so a search for a sign-in code finds nothing.

## Path parameters

- `address` string, required

## Query parameters

- `q` string, required
- `mode` 'hybrid' | 'semantic' | 'keyword'
- `limit` integer
- `since` string, date-time
- `until` string, date-time
- `folder` 'inbox' | 'archive' | 'sent' | 'spam' | 'trash' | 'anywhere'
- `from` string
- `label` string

## Response `200`

Ranked results

- object
  - `results` object[]
    - `message` object
      - `id` string
      - `mailbox` string
      - `thread_key` string
      - `direction` string
      - `from` string
      - `to` string
      - `subject` string, nullable
      - `snippet` string: The message's own words, first 200 characters.
      - `created_at` string
      - `folder` string
      - `is_read` boolean
    - `score` number: Fused rank score with a small recency boost; higher is better.
    - `why` 'words' | 'meaning' | 'both' | 'filter': words: the query's words matched; meaning: only the embedding did; both; filter: operators alone selected it.
    - `highlight` string, nullable: A fragment with the matched words in brackets, when words matched.
  - `mode` 'hybrid' | 'semantic' | 'keyword'
  - `query` string
  - `took_ms` integer
  - `hint` string

## Other responses

- `400`: Missing or invalid query
- `401`: Missing or invalid API key
- `404`: Mailbox not found
- `429`: Rate limit exceeded - wait and retry

---

[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)