mail_search

Gate: ungated · no kind, zero authority · read

Finds messages without moving them: the query becomes IMAP SEARCH criteria and the server does the matching. That is the whole point — a mailbox is unbounded and not ours, so pulling it down to filter locally would move a decade of mail over the wire, and indexing it into the knowledge corpus would let anyone who knows the address write into the assistant's retrieval. It is a substring search, not a semantic one: roof will not find Dachdecker.

Input

Field	Type	Required	Notes
text	string	no	Text to find anywhere in headers or body.
from	string	no	Only messages whose From header contains this.
since	string	no	Only messages on or after this date, YYYY-MM-DD. Only the date is used; the server ignores time and zone.
folder	string	no	Folder to search; defaults to INBOX.
limit	integer	no	How many messages — default 10, capped at 50.

Output

The same shape as mail_list: {"messages": [...]} with uid, from, subject, date and unread, newest first. A limit cuts to the newest matches, so a search for a common word does not answer with the oldest mail in the mailbox.

From JavaScript

nocturn.call

const hits = nocturn.call("mail_search", { text: "Rechnung", since: "2026-01-01", limit: 20 });

Notes

Every field narrows together — an "and", not an "or". Fields left out simply do not constrain, so a query with only limit is the same as a listing.