search-messages
Find Apple Mail messages using filters for text, sender, subject, date, read, or flagged status, then get matching IDs for subsequent email operations.
Instructions
Use when: finding messages by query/sender/subject/date/read/flag filters and you need their ids for follow-up operations. Returns: matching messages with id, date, subject, sender, and read state (plus partial-coverage diagnostics when some mailboxes were skipped). 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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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, sender, or content | |
| dateTo | No | End date filter (e.g., 'March 1, 2026') | |
| isRead | No | Filter by read status | |
| 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') | |
| isFlagged | No | Filter by flagged status |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| partial | No | ||
| messages | No | ||
| failedMailboxes | No | ||
| timedOutAccounts | No | ||
| notSearchedMailboxes | No | ||
| skippedLargeMailboxes | No |