Skip to navigation
API ReferenceToolsEmail

Search emails

Beta

Search the caller’s connected Gmail or Outlook mailbox.

Results come from the connected account the caller can access in their current workspace (the default account unless catalog_id names another). Unsent drafts are included and flagged with is_draft.

Authentication

X-API-KEYstring
API Key authentication via header

Headers

X-Athena-Session-CredentialstringOptional

Query parameters

querystringRequired>=1 character

Search query. Gmail operators (from:, to:, subject:, has:attachment, newer_than:7d, -term, …) are accepted for both providers; operators with no Outlook equivalent are dropped and reported in ignored_operators. Use in:drafts to search only unsent drafts.

catalog_idstring or nullOptional
Connected email account to use, as the catalog asset id returned by the Athena UI or the assets API. Defaults to the caller's default email account. An id that is not one of the caller's own connected accounts in the current workspace is a 404.
limitintegerOptional1-50Defaults to 20

Maximum number of results (1-50).

Response

Successful Response
catalog_idstring
The connected account that was searched.
countinteger
Number of results returned.
providerstring

Account provider as Athena reports it: gmail or outlook for accounts connected through the Integrations page; google or microsoft365 for directly-connected accounts.

querystring
The query as executed.
draft_countintegerOptionalDefaults to 0
How many of the results are unsent drafts.
ignored_operatorslist of strings or nullOptional
Gmail search operators that have no Outlook equivalent and were dropped from the query. Outlook accounts only.
notestring or nullOptional

Human-readable caveats about the results, when there are any.

resultslist of objectsOptional
Matching messages, newest first.

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error
429
Too Many Requests Error
502
Bad Gateway Error