search_messages
Search email messages in Apple Mail by criteria like sender, subject, date, read status, or content. Filter results with multiple conditions to locate specific messages quickly.
Instructions
Search for messages matching criteria. Returns metadata-only rows.
Two corpus modes:
source=None(default): search the given account/mailbox using the IMAP/AppleScript SEARCH path.accountis required.source=[id1, id2, ...]: scope the search to the specific messages identified by the given ids.account/mailboxare ignored; the connector resolves each id self-sufficiently. The resulting message dicts are post-filtered by the other criteria (sender_contains,read_status, etc.) — full filter composition. The literal token"SELECTED"may appear in the list and is server-resolved at call time to Mail.app's current UI selection (zero-or-more messages). Mixed lists like["SELECTED", "12345"]are valid. Missing ids drop out silently (partial-results).
For thread retrieval, call get_thread(message_id) to expand an
anchor into thread member ids, then optionally pipe those ids into
source=[ids] for filtered metadata browsing or into
get_messages([ids]) for full bodies.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum results to return (default: 50). | |
| source | No | Optional list of message ids (with optional ``"SELECTED"`` sentinel) to restrict the search to. ``None`` (default) searches the account/mailbox normally. | |
| account | No | Mail.app account display name (e.g., "Gmail", "iCloud") or UUID (from list_accounts). Required when ``source is None``; ignored when ``source`` is a list. Names are convenient but unstable across renames; UUIDs are stable. | |
| date_to | No | Inclusive upper bound on date received (full day included). ISO 8601 YYYY-MM-DD. | |
| mailbox | No | Mailbox name. Defaults to the account's real receiving mailbox, which is resolved by asking Mail instead of assuming it is called "INBOX" (it is not, on some accounts). Ignored when ``source`` is a list. | |
| date_from | No | Inclusive lower bound on date received. ISO 8601 YYYY-MM-DD. | |
| is_flagged | No | Filter by flagged status (true=flagged, false=not flagged). | |
| read_status | No | Filter by read status (true=read, false=unread). | |
| body_contains | No | Substring match against message body content. IMAP uses ``BODY`` predicate (sub-second); AppleScript reads ``content of msg`` per candidate (very slow on large mailboxes — measured 148s for 100 cold-cache messages). When the call commits to AppleScript with this filter set, a ``warnings`` field is included in the response. Case-insensitive on both paths. | |
| text_contains | No | Substring match against headers + body (RFC 3501 ``TEXT`` semantics). On AppleScript, approximated as ``content + subject + sender`` (recipients and other headers not matched). Same perf characteristics as ``body_contains``. | |
| has_attachment | No | Filter messages with (true) or without (false) attachments. | |
| sender_contains | No | Filter by sender email/domain substring. | |
| subject_contains | No | Filter by subject keywords substring. | |
| include_attachments | No | When True, each row includes an ``attachments`` field listing per-attachment metadata (name, mime_type, size, downloaded). Default False — opt-in because the AppleScript fallback path can be slow on cold caches (#142). Free on the IMAP fast path. To fetch attachment metadata for a known list of ids cheaply, prefer ``get_messages([ids])`` (default-on attachments, bounded cardinality). | |
| received_within_hours | No | Relative-time filter. When set, only return messages received within the last N hours (hour precision). Composes with ``date_from`` / ``date_to`` — the most restrictive filter wins. Must be a positive int. Days = 24, weeks = 168, etc. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||