Search mail

Requires scope: read. Full-text search over received and sent mail (subject, body text and addresses), newest first. Each hit says whether it was received or sent and carries a snippet around the match. Never leaves the workspace; a key tied to one agent searches that agent's mail; a test key searches test mail only and a live key live mail only. A search that runs past 5 seconds is stopped (400, narrow it), and a workspace may search 120 times a minute (429 with Retry-After past that).

get/v1/search

Request

Base URL: https://api.mails.ai
URL: https://api.mails.ai/v1/search
Auth: HTTP bearer

Query parameters

qstring

Full-text search: every word must appear in the subject, body or addresses, as a whole word or, from three letters up, the start of one (inv finds invoice). At most 16 different words (more is a 400).

agent_idstring

Filter by agent id or name. A key tied to one agent always reads that agent's mail, and naming another agent is a 403.

fromstring

The sender's address contains this text (the display name, which the sender chooses, is not matched).

tostring

A recipient address contains this text.

afterstring

Only mail at or after this time (ISO 8601, or YYYY-MM-DD).

beforestring

Only mail before this time (ISO 8601, or YYYY-MM-DD).

has_attachmentboolean

true for mail with a file attachment, false for mail without.

Which folder's mail to return, or all for every folder. Without it: every folder except trash.

labelstring

Only mail in threads carrying this label (a name, or a label id lbl_…).

type'received' | 'sent'

Only received or only sent mail.

limitinteger

Page size (1–100).

cursorstring

Opaque cursor from a previous page's next_cursor.

Response

A page of hits.

has_moreboolean required

True when more items follow this page: pass next_cursor as cursor to get them.

next_cursorstring

Pass as cursor to fetch the next page. Absent on the last page.

Changes

No recorded changes to this operation across all 1 revision of this API.