search-messages
Find messages by query, sender, subject, date, read, flag, or flag-color filters and return matching IDs for follow-up operations.
Instructions
Use when: finding messages by query/sender/subject/date/read/flag/flag-color filters and you need their ids for follow-up operations. Returns: matching messages with id, date, subject, sender, read state, and flagColor when flagged with an explicit color (plus partial-coverage diagnostics when some mailboxes were skipped). An IMAP search stops at its deadline (APPLE_MAIL_MCP_SEARCH_DEADLINE_MS, default 45s) or when the request is cancelled, returning the matches found so far with partial: true and timedOutMailboxes — narrow with mailbox/dateFrom rather than repeating it. Do not use when: you want a plain mailbox listing without filters (use list-messages), already have an id and want the body (use get-message), or want a whole conversation (use get-thread). Prefer this first to obtain the message ids that get-message/mark-as-read/delete-message/move-message and the batch tools require. Tip: use flagColor to find messages you tagged earlier (e.g. all 'orange' across mailboxes) — colored flags work as cross-mailbox labels this way, via flag-message/batch-flag-messages to set them and this filter to find them again, without moving anything into a dedicated folder.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Text to search for in the message body (server-side IMAP BODY search). Requires the IMAP backend for the account searched, or the opt-in local body index (APPLE_MAIL_MCP_BODY_INDEX); otherwise AppleScript-only accounts cannot search bodies and are reported as not searched. | |
| from | No | Filter by sender (substring match against the full sender string, i.e. display name + address — not an exact address match) | |
| limit | No | Maximum number of results (default: 50, max: 500) | |
| query | No | Text to search for in subject or sender | |
| dateTo | No | End date filter (e.g., 'March 1, 2026') | |
| isRead | No | Filter by read status | |
| offset | No | Number of newest matches to skip (for pagination; IMAP accounts only). Without a mailbox, offset + limit may not exceed 5,000 — name a mailbox to page deeper. | |
| account | No | Account to search in (omit to search all accounts) | |
| mailbox | No | Mailbox to search in (e.g., 'INBOX'). Omit to search all mailboxes. | |
| subject | No | Filter by subject line (substring match) | |
| dateFrom | No | Start date filter (e.g., 'January 1, 2026') | |
| flagColor | No | Filter to messages flagged with exactly this color (same palette as flag-message: red/orange/yellow/green/blue/purple/gray — 'grey' accepted). A message flagged with Mail's plain default (no explicit color) never matches. Implies isFlagged: true — pairing this with isFlagged: false is rejected as contradictory. Caveat on IMAP accounts only: 'red' is Mail's all-bits-clear encoding, wire-identical to a plain (colorless) flag, so red: true in results and flagColor: 'red' in this filter both also match a plain flag there — this is inherent to Apple's $MailFlagBit0/1/2 scheme, not specific to this server. AppleScript-only accounts distinguish red correctly (Mail's own `flag index` 0 vs -1). | |
| isFlagged | No | Filter by flagged status |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| backend | No | ||
| partial | No | ||
| messages | No | ||
| stoppedBy | No | ||
| failedMailboxes | No | ||
| omittedMessages | No | ||
| backendByAccount | No | ||
| timedOutAccounts | No | ||
| timedOutMailboxes | No | ||
| failedMailboxReasons | No | ||
| notSearchedMailboxes | No | ||
| skippedLargeMailboxes | No |