---
title: "Search Messages"
method: GET
path: "/v0/inboxes/{inbox_id}/messages/search"
tags: ["InboxesMessages"]
---

# Search Messages

`GET /v0/inboxes/{inbox_id}/messages/search`

Full-text search across messages in the inbox, ranked by relevance. The
query is matched against the sender, recipients, and subject (substring)
and the message body (tokenized full text). Spam, trash, blocked, and
unauthenticated messages are always excluded. `limit` cannot exceed 100.

## Path parameters

- `inbox_id` string, required — The ID of the inbox.

## Query parameters

- `q` string, required — Full-text search query. Matched against the sender, recipients, and subject (substring) and the message body (tokenized full text).
- `limit` integer — Limit of number of items returned.
- `page_token` string — Page token for pagination.
- `before` string, date-time — Timestamp before which to filter by.
- `after` string, date-time — Timestamp after which to filter by.

## Response `200`

- SearchMessagesResponse
  - `count` integer, required — Number of items returned.
  - `limit` integer — Limit of number of items returned.
  - `next_page_token` string — Page token for pagination.
  - `messages` SearchMessageItem[], required — Ordered by relevance, best match first.
    - `inbox_id` string, required — The ID of the inbox.
    - `thread_id` string, required — ID of thread.
    - `message_id` string, required — ID of message.
    - `labels` string[], required — Labels of message.
    - `timestamp` string, date-time, required — Time at which message was sent or drafted.
    - `from` string, required — Address of sender. In format `username@domain.com` or `Display Name <username@domain.com>`.
    - `to` string[], required — Addresses of recipients. In format `username@domain.com` or `Display Name <username@domain.com>`.
    - `cc` string[] — Addresses of CC recipients. In format `username@domain.com` or `Display Name <username@domain.com>`.
    - `bcc` string[] — Addresses of BCC recipients. In format `username@domain.com` or `Display Name <username@domain.com>`.
    - `subject` string — Subject of message.
    - `preview` string — Text preview of message.
    - `attachments` Attachment[] — Attachments in message.
      - `attachment_id` string, required — ID of attachment.
      - `filename` string — Filename of attachment.
      - `size` integer, required — Size of attachment in bytes.
      - `content_type` string — Content type of attachment.
      - `content_disposition` 'inline' | 'attachment' — Content disposition of attachment.
      - `content_id` string — Content ID of attachment.
    - `in_reply_to` string — ID of message being replied to.
    - `references` string[] — IDs of previous messages in thread.
    - `headers` MessageHeaders — Headers in message.
    - `size` integer, required — Size of message in bytes.
    - `updated_at` string, date-time, required — Time at which message was last updated.
    - `created_at` string, date-time, required — Time at which message was created.

## Other responses

- `400`
- `404`

---

[API](https://skmtc.net/agentmail-to/apis/api.md) · [All operations](https://skmtc.net/agentmail-to/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agentmail-to/api/revisions/394ddcdd9c29/schema)