fetch_emails
Retrieve emails from an IMAP mailbox with configurable filters for date ranges, limits, and offsets to manage email access.
Instructions
Fetch emails from mailbox with optional filters
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mailbox | No | Mailbox name (default: current) | |
| limit | No | Max emails to fetch (default: 20) | |
| offset | No | Skip first N emails (default: 0) | |
| since | No | Emails since date (ISO format) | |
| before | No | Emails before date (ISO format) |
Implementation Reference
- src/imap_mcp/imap_client.py:263-302 (handler)The 'fetch_emails' method in the 'ImapClientWrapper' class handles fetching email headers from an IMAP mailbox using IMAP search criteria, sorting, and pagination. It also parses the IMAP response into EmailHeader objects.
def fetch_emails( self, mailbox: Optional[str] = None, limit: int = 20, offset: int = 0, since: Optional[str] = None, before: Optional[str] = None, ) -> list[EmailHeader]: """Fetch emails from mailbox with optional filters.""" self._ensure_connected() if mailbox: self.select_mailbox(mailbox) elif not self.current_mailbox: self.select_mailbox("INBOX") # Build search criteria criteria = ["ALL"] if since: criteria = ["SINCE", since] if before: if len(criteria) > 1: criteria.extend(["BEFORE", before]) else: criteria = ["BEFORE", before] uids = self.client.search(criteria) # Apply offset and limit (newest first) uids = sorted(uids, reverse=True) if offset: uids = uids[offset:] if limit: uids = uids[:limit] if not uids: return [] messages = self.client.fetch(uids, ["ENVELOPE", "FLAGS", "RFC822.SIZE"]) return [self._parse_email_header(uid, data) for uid, data in messages.items()] - src/imap_mcp/imap_client.py:263-301 (handler)The core logic for fetching emails from the IMAP mailbox.
def fetch_emails( self, mailbox: Optional[str] = None, limit: int = 20, offset: int = 0, since: Optional[str] = None, before: Optional[str] = None, ) -> list[EmailHeader]: """Fetch emails from mailbox with optional filters.""" self._ensure_connected() if mailbox: self.select_mailbox(mailbox) elif not self.current_mailbox: self.select_mailbox("INBOX") # Build search criteria criteria = ["ALL"] if since: criteria = ["SINCE", since] if before: if len(criteria) > 1: criteria.extend(["BEFORE", before]) else: criteria = ["BEFORE", before] uids = self.client.search(criteria) # Apply offset and limit (newest first) uids = sorted(uids, reverse=True) if offset: uids = uids[offset:] if limit: uids = uids[:limit] if not uids: return [] messages = self.client.fetch(uids, ["ENVELOPE", "FLAGS", "RFC822.SIZE"]) return [self._parse_email_header(uid, data) for uid, data in messages.items()] - src/imap_mcp/server.py:502-509 (registration)The MCP tool handler that invokes fetch_emails when the 'fetch_emails' tool is called.
elif name == "fetch_emails": return imap_client.fetch_emails( mailbox=args.get("mailbox"), limit=args.get("limit", 20), offset=args.get("offset", 0), since=args.get("since"), before=args.get("before"), )