---
title: "Semantic search across your inbox."
method: POST
path: "/v1/messages/search"
tags: ["Messages"]
---

# Semantic search across your inbox.

`POST /v1/messages/search`

## Request

- Base URL: `https://api.inboxy.net`
- URL: `https://api.inboxy.net/v1/messages/search`
- Auth: HTTP bearer

Embeds the query with the same model the classifier writes with, then runs a vector query against your messages. `user_id` filter is mandatory and applied server-side — you cannot omit or override it.

## Request body

- SearchRequest
  - `query` string, required
  - `limit` integer
  - `filters` object
    - `address_id` string, uuid
    - `classification` 'otp' | 'login_link' | 'verify' | 'receipt' | 'notice' | 'marketing' | 'spam' | 'other'
    - `from_domain` string
    - `since` string, date-time

## Response `200`

Ranked matches.

- object
  - `results` SearchResult[]
    - `id` string, uuid, required
    - `address_id` string, uuid
    - `from_email` string, email, required
    - `from_label` string, nullable
    - `subject` string, nullable
    - `received_at` integer, required: Unix seconds.
    - `classification` 'otp' | 'login_link' | 'verify' | 'receipt' | 'notice' | 'marketing' | 'spam' | 'other'
    - `urgency` 'low' | 'normal' | 'high' | 'null', nullable
    - `summary` string, nullable
    - `confidence` number, nullable
    - `read` boolean, required
    - `pending_classification` boolean
    - `forwarded_at` integer, nullable
    - `body_lost` boolean
    - `kept_at` integer, nullable: Unix seconds when the user pinned this message to bypass the retention sweep. Null = not kept.
    - `score` number, required: Cosine similarity, 0..1.

## Other responses

- `400`: Malformed request.

---

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