Skip to main content
Searches the mailbox and returns a compact, newest-first hit list without message bodies. Combine free text with any of the structured filters; at least one filter is required. Fetch a full message with get_email.

​
Parameters

​
query
string
Free-text full-text search over subject and body. 1–500 characters.
​
after
string
Only messages received on or after this UTC ISO 8601 timestamp, e.g. 2026-04-01T00:00:00Z.
​
before
string
Only messages received strictly before this UTC ISO 8601 timestamp, e.g. 2026-07-01T00:00:00Z.
​
from
string
Substring match on the sender’s name or address. 1–200 characters.
​
keywords
string[]
Category labels to filter by; multiple values combine with OR. At least one value when present. Valid values:
ValueMeaning
directPersonal emails from individuals and direct conversations
receiptOrder confirmations, shipping updates, delivery notifications, purchase receipts
newsletterRegular updates, news digests, curated content
notificationSecurity alerts, terms updates, service notifications
promotionalMarketing emails, sales pitches, discount offers
todoMessages flagged as an action item — see Email intelligence
​
mailbox
string
Restrict to a named mailbox/folder, e.g. Inbox.
​
limit
integer
default:"20"
Maximum results, 1–100.

​
Example

Call
{
  "query": "invoice",
  "keywords": ["receipt"],
  "after": "2026-06-01T00:00:00Z",
  "limit": 10
}
Result
2 message(s) matched:

1. Your invoice for June
   id: Mabc123
   from: Acme Billing <billing@acme.example>
   date: 2026-07-05T08:12:00Z
   tags: receipt

2. Invoice #4021
   id: Mab9f01
   from: Hosting Co <billing@hosting.example>
   date: 2026-06-14T07:30:00Z
   tags: receipt
Messages with no category tags omit the tags: line. An empty result returns No messages matched.

​
Errors

  • Provide at least one filter: query, after, before, from, keywords, or mailbox. — the call had no filter.
  • Mailbox not found: <name> — the mailbox value didn’t match a folder.