search
searchFind locally synced emails by text, sender, recipient, subject, body, attachment content, folder, or date; then read matching messages.
Instructions
Search locally synced messages in one connection. Choose query and field for text search; optionally restrict by folder and dates. Text results are most relevant first. To list messages by date alone, omit query and supply since or until; results are newest first, without snippets.
Subject, body and attachment text support Russian and English word forms; irregular forms and synonyms may be missed. If results are sparse, try fewer words, other forms, synonyms or the other language in separate calls. An empty result does not prove the mail is absent: only synced, indexed content is searched.
Read a hit with getMessage using the same connection and the hit's key. Snippets mark matches as word, but may show only part of a match or body context. If a hit has snippetAttachmentFile, read that attachment with getAttachment using the same connection, the hit's key and file=snippetAttachmentFile. Recognized copies are returned once; copies lists other matching keys and folders. total and paging count these groups.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| field | No | Choose one: any (default; all fields below), subject, body, from, to (includes Cc), attachmentName (whole name or parts), attachmentText (extracted contents), label (mailbox label words, such as Gmail's Inbox, Sent or user labels; connections without labels match nothing). from/to search addresses and names. For an exact address match, use an unquoted full address: field=from, query=user@example.com. This ignores case and display names. any also searches content, so an address there need not be a participant. Without query, field has no effect | |
| limit | No | Results per page: 1 to 100, default 20; larger values are capped at 100 | |
| query | No | Search terms, a quoted phrase or a full email address; at most 1000 characters. Words combine with AND (common stop words may be ignored); double quotes make a phrase. No OR/NOT, wildcards, fuzzy matching or field-prefix syntax such as from:. Search alternatives in separate calls. Omit only when since or until is given | |
| since | No | Include messages at or after this date/time, using the message Date header, not receipt or download time. Format: YYYY-MM-DD (UTC midnight), or ISO-8601 with Z or an offset, e.g. 2026-10-01T09:00:00+03:00; at most 3 fractional second digits. Messages without a date are excluded | |
| until | No | Include messages strictly before this date/time; same header and format as since. To include a whole day, use the following day's midnight. Must be later than since when both are given. Messages without a date are excluded | |
| folder | No | One folder key from listFolders, not its display name. Omit to search all folders in the connection | |
| offset | No | Default 0. For the next page, repeat the same search arguments and use the previous nextOffset. Stop when there is no nextOffset | |
| connection | Yes | Connection name from listConnections |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hits | Yes | Hits, most relevant first; newest first for date-only search. | |
| field | Yes | Field searched. | |
| query | No | Text query; absent for date-only search. | |
| since | No | Applied since bound, in UTC. | |
| total | Yes | Matching messages; copies of one message count once. | |
| until | No | Applied until bound, in UTC. | |
| folder | No | Folder key searched; absent for all folders. | |
| offset | Yes | Position of this page. | |
| connection | Yes | Connection name. | |
| nextOffset | No | Pass as offset to get the next page; absent at the end. |