Appearance
Search API
Full-text search over indexed archived emails, powered by Meilisearch.
Search Emails
Search archived emails
GET
/v1/search
Performs a full-text search across indexed archived emails using Meilisearch, with optional advanced filters. List-valued parameters accept comma-separated values; list values are OR-combined within a parameter and AND-combined across parameters. Requires search:archive permission.
Authorizations
bearerAuth
JWT obtained from POST /v1/auth/login. Pass as Authorization: Bearer <token>.
Type
HTTP (bearer)
or
apiKeyAuth
API key generated via POST /v1/api-keys. Pass as X-API-KEY: <key>.
Type
API Key (header: X-API-KEY)
Parameters
Query Parameters
keywords
The search query string. Required unless at least one filter parameter is provided (filter-only browsing).
Type
string
Example
"invoice Q4"sources
Comma-separated ingestion source IDs to include. Each ID is expanded to its full merge group.
Type
string
Example
"3f6e…a1,9c2b…e7"excludeSources
Comma-separated ingestion source IDs to exclude. Each ID is expanded to its full merge group.
Type
string
from
Comma-separated sender addresses to include.
Type
string
Example
"[email protected],[email protected]"notFrom
Comma-separated sender addresses to exclude.
Type
string
to
Comma-separated recipient addresses to include. Matches the To, Cc, or Bcc field.
Type
string
notTo
Comma-separated recipient addresses to exclude from To, Cc, and Bcc.
Type
string
mailboxes
Comma-separated mailbox owner addresses (the account an email was archived from).
Type
string
dateFrom
Inclusive start date (UTC), yyyy-mm-dd.
Type
string
Example
"2025-01-01"Format
"date"dateTo
Inclusive end date (UTC), yyyy-mm-dd.
Type
string
Example
"2025-12-31"Format
"date"searchIn
Comma-separated parts of the email to match keywords against. Any of subject, body, attachment_name, attachment_content, from, to. Omitted = search everywhere.
Type
string
Example
"subject,attachment_name"hasAttachments
Filter by attachment presence. Emails indexed before this field existed count as attachment-less until reindexed.
Type
boolean
sort
Result ordering. date_desc (default) and date_asc sort by sent date; relevance uses Meilisearch ranking.
Type
string
Valid values
"relevance""date_desc""date_asc"Default
"date_desc"page
Page number for pagination.
Type
integer
Example
1Default
1limit
Number of results per page.
Type
integer
Example
10Default
10matchingStrategy
Meilisearch matching strategy. last returns results containing at least one keyword; all requires all keywords; frequency sorts by keyword frequency.
Type
string
Valid values
"last""all""frequency"Default
"last"Responses
Search results.
application/json
JSON "hits": [ { } ], "total": 42, "page": 1, "limit": 10, "totalPages": 5, "processingTimeMs": 12
{
}
Suggest Facet Values (Typeahead)
Returns prefix-matched, permission-scoped values for a facet field — used to power the mailbox and sender autocomplete in the advanced search filters. A partial token such as gmail suggests full addresses like [email protected], and results respect the caller's permissions.
Suggest facet values (typeahead)
GET
/v1/search/facets
Returns prefix-matched, permission-scoped distinct values for a facet field, for autocomplete inputs such as the mailbox filter. Requires search:archive permission.
Authorizations
bearerAuth
JWT obtained from POST /v1/auth/login. Pass as Authorization: Bearer <token>.
Type
HTTP (bearer)
or
apiKeyAuth
API key generated via POST /v1/api-keys. Pass as X-API-KEY: <key>.
Type
API Key (header: X-API-KEY)
Parameters
Query Parameters
field*
The facet field to suggest values for.
Type
Requiredstring
Valid values
"mailboxes""from"query
The partial value typed so far; empty returns the most common values.
Type
string
Example
"ali"Responses
Matching facet values.
application/json
JSON