search_emails
Search emails in your mailbox using IMAP criteria like sender, subject, or status to find specific messages quickly.
Instructions
Search emails with criteria
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| folder | No | Folder to search in (default: INBOX) | INBOX |
| criteria | No | IMAP search criteria (e.g., 'ALL', 'UNSEEN', 'FROM sender@example.com', 'SUBJECT urgent') | ALL |
| limit | No | Maximum number of results (default: 10) |
Implementation Reference
- The core implementation of the search_emails logic as part of the EmailSearch class.
def search_emails( self, folder: str, conditions: dict[str, Any], charset: str | None = None ) -> list[int]: """ Search for emails matching conditions. Args: folder: Folder to search in conditions: Dictionary of search conditions Supported keys: - subject, from, to, cc, bcc, body, text: Search in fields - since, before, on: Date conditions (YYYY-MM-DD or date object) - seen/unseen, answered/unanswered, flagged/unflagged, deleted/undeleted: Flag conditions - uid: UID search charset: Character set for search (default: None/UTF-8) Returns: List of email sequence numbers Raises: EmailSearchError: If search fails Example: - src/mail_mcp/tools/__init__.py:476-482 (registration)The registration and invocation handler for the 'search_emails' tool in the MCP tools dispatcher.
elif name == "search_emails": result = client.search_emails( folder=arguments.get("folder", "INBOX"), criteria=arguments.get("criteria", "ALL"), limit=arguments.get("limit", 10), ) return [TextContent(type="text", text=str(result))]