imap_search_emails
Search emails by sender, recipient, subject, body, date range, or read/flagged status, in one folder or all mailboxes. Locate messages by details without needing their UID.
Instructions
Note: on some servers a 'flagged' or starred message carries a custom keyword (e.g. an Open-Xchange color label or Apple's $MailFlagBit*) instead of, or in addition to, the \Flagged system flag. After any flagged search, inspect each result's customKeywords field before concluding a message is or isn't flagged — do not rely on the flagged filter alone. Search for emails matching criteria (sender, recipient, subject, body text, date range, read/flagged status). Use this to FIND messages when you know something about them but not their UID — e.g. "emails from amazon last week", "unread invoices". By default searches a single folder (INBOX). Set searchAllFolders=true to scan every mailbox at once — this catches messages filed away by rules (e.g. a receipt routed to a custom folder); Trash/Spam/Drafts are skipped unless you opt in. By default returns lightweight headers (uid, from, subject, date, and folder when searching across folders); set includeBody=true to also return the parsed body in one round-trip instead of paying the N+1 cost of calling imap_get_email per match. For the newest messages without criteria, prefer imap_get_latest_emails.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Search by recipient | |
| body | No | Search in body text | |
| from | No | Search by sender | |
| seen | No | Filter by read/unread status | |
| limit | No | Maximum number of results | |
| since | No | Search emails since date (YYYY-MM-DD) | |
| before | No | Search emails before date (YYYY-MM-DD) | |
| folder | No | Folder name to search (default: INBOX). Ignored when searchAllFolders is true. | INBOX |
| flagged | No | Filter by flagged status | |
| subject | No | Search by subject | |
| keywords | No | Match messages that have ANY of these CUSTOM keywords (server-side OR; not system flags like \Seen/\Flagged). Read a mailbox's available custom keywords from imap_folder_status's customKeywords field, then pass the ones you want here. | |
| accountId | No | Account ID (from imap_list_accounts). Optional if accountName is given or only one account is configured. | |
| messageId | No | Search by RFC822 Message-ID header (substring match) | |
| bodyFormat | No | How to render the body when `includeBody` is true. Mirrors `imap_get_email` — "markdown" (default) returns clean Markdown and omits raw HTML so it never crosses the MCP boundary; "text" returns plain text; "html" returns raw HTML; "auto" prefers substantive text/plain, else Markdown. | markdown |
| unKeywords | No | Exclude messages that have ANY of these CUSTOM keywords (server-side; result has NONE of them). Same keyword source as `keywords` — check imap_folder_status first. | |
| accountName | No | Account name instead of accountId. Optional if accountId is given or only one account is configured. | |
| includeBody | No | If true, also fetch the parsed message body in the same round-trip and return it alongside headers (avoids the N+1 cost of calling imap_get_email per match). Body is rendered per `bodyFormat` and capped at `bodyMaxLength` characters per field. Off by default to preserve lightweight behavior. | |
| includeSpam | No | When searchAllFolders is true, also search Spam/Junk folders (off by default — noisy). | |
| includeTrash | No | When searchAllFolders is true, also search Trash/Bin/Deleted folders (off by default — noisy). | |
| bodyMaxLength | No | Per-message cap (in characters) for each rendered body field when `includeBody` is true. Defaults to 10000 to match `imap_get_email`. | |
| includeDrafts | No | When searchAllFolders is true, also search the Drafts folder (off by default). | |
| searchAllFolders | No | Search across ALL folders instead of just `folder`. Skips Trash/Spam/Drafts and non-selectable folders by default. Use when a message might have been filed/archived/moved and you do not know which folder it is in. |