list_emails_metadata
Retrieve email metadata including subject, sender, recipients, and date. Filter by mailbox, date range, sender, subject, read status, and more. Obtain email IDs to fetch full content separately.
Instructions
List email metadata (email_id, subject, sender, recipients, date) without body content. Returns email_id for use with get_emails_content.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| account_name | Yes | The name of the email account. | |
| page | No | The page number to retrieve (starting from 1). | |
| page_size | No | The number of emails to retrieve per page. | |
| before | No | Retrieve emails before this datetime (UTC). | |
| since | No | Retrieve emails since this datetime (UTC). | |
| subject | No | Filter emails by subject. | |
| from_address | No | Filter emails by sender address. | |
| to_address | No | Filter emails by recipient address. | |
| order | No | Order emails by field. `asc` or `desc`. | desc |
| mailbox | No | The mailbox to search. | INBOX |
| seen | No | Filter by read status: True=read, False=unread, None=all. | |
| flagged | No | Filter by flagged/starred status: True=flagged, False=unflagged, None=all. | |
| answered | No | Filter by replied status: True=replied, False=not replied, None=all. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | Yes | ||
| page_size | Yes | ||
| before | Yes | ||
| since | Yes | ||
| subject | Yes | ||
| emails | Yes | ||
| total | Yes |
Implementation Reference
- mcp_email_server/app.py:46-100 (handler)The MCP tool function 'list_emails_metadata' registered with @mcp.tool decorator. It accepts filtering parameters (page, page_size, before, since, subject, from_address, to_address, order, mailbox, seen, flagged, answered) and dispatches to handler.get_emails_metadata().
async def list_emails_metadata( account_name: Annotated[str, Field(description="The name of the email account.")], page: Annotated[ int, Field(default=1, description="The page number to retrieve (starting from 1)."), ] = 1, page_size: Annotated[int, Field(default=10, description="The number of emails to retrieve per page.")] = 10, before: Annotated[ datetime | None, Field(default=None, description="Retrieve emails before this datetime (UTC)."), ] = None, since: Annotated[ datetime | None, Field(default=None, description="Retrieve emails since this datetime (UTC)."), ] = None, subject: Annotated[str | None, Field(default=None, description="Filter emails by subject.")] = None, from_address: Annotated[str | None, Field(default=None, description="Filter emails by sender address.")] = None, to_address: Annotated[ str | None, Field(default=None, description="Filter emails by recipient address."), ] = None, order: Annotated[ Literal["asc", "desc"], Field(default=None, description="Order emails by field. `asc` or `desc`."), ] = "desc", mailbox: Annotated[str, Field(default="INBOX", description="The mailbox to search.")] = "INBOX", seen: Annotated[ bool | None, Field(default=None, description="Filter by read status: True=read, False=unread, None=all."), ] = None, flagged: Annotated[ bool | None, Field(default=None, description="Filter by flagged/starred status: True=flagged, False=unflagged, None=all."), ] = None, answered: Annotated[ bool | None, Field(default=None, description="Filter by replied status: True=replied, False=not replied, None=all."), ] = None, ) -> EmailMetadataPageResponse: handler = dispatch_handler(account_name) return await handler.get_emails_metadata( page=page, page_size=page_size, before=before, since=since, subject=subject, from_address=from_address, to_address=to_address, order=order, mailbox=mailbox, seen=seen, flagged=flagged, answered=answered, ) - mcp_email_server/app.py:43-45 (registration)The @mcp.tool decorator registering 'list_emails_metadata' as an MCP tool with a description explaining it lists email metadata without body content.
@mcp.tool( description="List email metadata (email_id, subject, sender, recipients, date) without body content. Returns email_id for use with get_emails_content." ) - EmailMetadataPageResponse - the return type schema for list_emails_metadata, containing page info, filters, email list, and total count.
class EmailMetadataPageResponse(BaseModel): """Paged email metadata response""" page: int page_size: int before: datetime | None since: datetime | None subject: str | None emails: list[EmailMetadata] total: int - EmailMetadata model representing individual email metadata returned by list_emails_metadata (email_id, subject, sender, recipients, date, attachments).
class EmailMetadata(BaseModel): """Email metadata""" email_id: str message_id: str | None = None # RFC 5322 Message-ID header for reply threading subject: str sender: str recipients: list[str] # Recipient list date: datetime attachments: list[str] @classmethod def from_email(cls, email: dict[str, Any]): return cls( email_id=email["email_id"], message_id=email.get("message_id"), subject=email["subject"], sender=email["from"], recipients=email.get("to", []), date=email["date"], attachments=email["attachments"], ) - ClassicEmailHandler class that implements get_emails_metadata(), which is called by the tool handler. It streams metadata from the IMAP EmailClient.
class ClassicEmailHandler(EmailHandler): def __init__(self, email_settings: EmailSettings): self.email_settings = email_settings self.incoming_client = EmailClient(email_settings.incoming) self.outgoing_client = EmailClient( email_settings.outgoing, sender=f"{email_settings.full_name} <{email_settings.email_address}>", ) self.save_to_sent = email_settings.save_to_sent self.sent_folder_name = email_settings.sent_folder_name async def get_emails_metadata(