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 and Sent, plus any archive folder list_mailboxes shows, and passing them all in mailboxes costs the user one call instead of several. A named folder the mailbox does not have is skipped and named in the result. 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. Looking for mail from or to a person is fastest with from or to, plus since when you know roughly when: the server answers those from its index. text and body make many servers read every message in each folder named, which on a large mailbox takes several seconds a folder. select_emails, by contrast, returns up to 500 UIDs grouped by sender for a bulk action.
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", "Sent"], plus any archive folder list_mailboxes shows. Defaults to ["INBOX"]. Up to 25. Naming several here is ONE call; searching them one at a time is one call each. |