Search emails
search_emailsSearch one or more IMAP folders and return summaries in exactly the shape list_emails returns plus the folder each was found in, newest first - including the same preview of the first line or two, so a search usually answers the question without a read_email after it. Not message bodies, though; read_email is the tool for reading one message in full. SEARCH EVERY FOLDER THE MESSAGE COULD BE IN, IN ONE CALL: "where is that email from Bob" usually means INBOX, Archive and Sent, and passing all three in mailboxes costs the user one call instead of three. Each result carries its own mailbox - pass that back when you act on it, because UIDs mean different messages in different folders. At least one criterion is required - an empty search is refused rather than silently returning the whole mailbox. from/to/cc/subject/body/text are SUBSTRING matches, not exact matches: searching from: "a@b.com" also matches "xa@b.commercial.example". since/before/on match the date the message was DELIVERED to this mailbox, not the sender's Date: header, and only at whole-day precision - the time of day is ignored. A result that had to be capped says so explicitly, together with the true total number of matches, so it is never mistaken for a complete list.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cc | No | Substring match against the Cc address or display name. | |
| on | No | Delivered on exactly this date (e.g. "2026-08-01"). Matches when the message arrived in this mailbox, not its Date: header. | |
| to | No | Substring match against the To address or display name. | |
| body | No | Substring match against the message body. | |
| from | No | Substring match against the From address or display name. | |
| seen | No | Filter by read/unread status. | |
| text | No | Substring match against headers and body together. | |
| limit | No | How many summaries to return, newest first. Defaults to 25. | |
| since | No | Delivered on or after this date (e.g. "2026-08-01"). Matches when the message arrived in this mailbox, not its Date: header. Whole-day precision only. | |
| before | No | Delivered before this date (e.g. "2026-08-01"). Matches when the message arrived in this mailbox, not its Date: header. Whole-day precision only. | |
| flagged | No | Filter by the flagged/starred state. | |
| subject | No | Substring match against the subject line. | |
| answered | No | Filter by whether the message has been answered. | |
| mailboxes | No | IMAP folders to search, e.g. ["INBOX", "Archive", "Sent"]. Defaults to ["INBOX"]. Up to 25. Use list_mailboxes if you do not know the folder names. Naming several here is ONE call; searching them one at a time is one call each. |