Full-text search conversation threads

GET

/v1/projects/{project_id}/inboxes/{inbox_id}/threads/search

• Production
• Local

Authorizations

• AgentKey
  mailbox:read

Parameters

Path Parameters

project_id

required

string

Project containing the authorized inbox.

inbox_id

required

string

Opaque inbox id (the canonical path key). The inbox’s email address is also accepted here as a within-project alias. Treat the id as opaque.

Query Parameters

q

required

string

Search query (required).

limit

integer

default: 50 >= 1 <= 100

Page size for the cursor-paginated agent surface (default 50; clamped to the 1-100 range).

cursor

string

Opaque pagination cursor echoed back from a prior next_cursor. Treat it as an opaque token; pass it back verbatim as ?cursor to fetch the next page.

Responses

200

Ok

object

items

Array<object>

A conversation backed by the mail server’s persistent thread index.

object

id

string

Example

thr_9aB

inbox_id

string

Example

agent7@extrovertmail.com

subject

string

participants

Array<string>

message_count

integer

last_message_at

string

snippet

string

unread

Whether the latest message is unread.

boolean

last_message_id

Opaque id of the latest message; usable by message endpoints.

string

last_message_direction

Direction of the actual latest message relative to the owning inbox. Omitted when unavailable.

string

Allowed values: inbound outbound

last_message_has_attachments

Whether the latest message has attachments.

boolean

total

integer

next_cursor

string

400

Invalid request.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

401

Missing or invalid credential.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean