search_messages
Search for messages using filters like sender, subject, date, read status, and attachment presence. Returns metadata-only results from a specified account or from a list of message IDs.
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 (default: "INBOX"). Ignored when ``source`` is a list. | INBOX |
| 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 | |||