advanced_search_metadata
Search emails with advanced filters (mailbox, sender, subject, date, attachment, unread, pinned) and return only metadata—no body content—to support privacy-sensitive routing and classification.
Instructions
Same filter capabilities as advanced_search (single-mailbox scoping via mailboxId, multi-mailbox intersection via requiredMailboxIds, exclusion via excludeMailboxIds, plus sender / recipient / subject / free text / date / attachment / unread / pinned) but returns ONLY metadata on each match — id, threadId, subject, from, to, cc, replyTo, receivedAt, hasAttachment, keywords. Does NOT return preview or any body-derived content. Use in privacy-sensitive flows where the routing decision is made from headers alone — for example, when classifying customer mail by sender / recipient / subject / thread state without ingesting body content. The free-text query still searches body content on the server side; only the result envelope comes back without body excerpts. When the server reports a total match count, results are wrapped in a {"total", "items"} JSON envelope; otherwise a bare JSON array is returned.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Filter by recipient email | |
| from | No | Filter by sender email | |
| after | No | Emails after this date (ISO 8601) | |
| limit | No | Maximum results (default: 50) | |
| query | No | Text to search for in subject/body | |
| before | No | Emails before this date (ISO 8601) | |
| subject | No | Filter by subject | |
| isPinned | No | Filter pinned emails | |
| isUnread | No | Filter unread emails | |
| ascending | No | Sort oldest first instead of newest first (default: false) | |
| mailboxId | No | Search within a single mailbox. For an intersection across multiple mailboxes (e.g. Inbox AND a label folder), use requiredMailboxIds instead. | |
| hasAttachment | No | Filter emails with attachments | |
| excludeMailboxIds | No | Exclude emails that are members of ANY of these mailbox IDs (maps to JMAP inMailboxOtherThan). Useful for queries like "in a parent label but not its archive sub-folder". Combines cleanly with mailboxId / requiredMailboxIds. | |
| requiredMailboxIds | No | Require membership in ALL of these mailbox IDs (intersection / AND semantic). Use this for queries like "in Inbox AND a label folder" — pass both mailbox IDs in the array. If mailboxId is also passed, it is folded into the intersection (de-duplicated). JMAP cannot express multi-mailbox membership in a single FilterCondition, so this builds a FilterOperator AND over multiple inMailbox conditions on the server. |