list_recent_senders
Identifies top email senders over a specified period, ordered by message count. Answers 'who has been emailing me lately?'
Instructions
Top senders over the last N days, ordered by message count. Useful for "who has been emailing me lately?" style questions.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | ||
| folder | No | INBOX | |
| since_days | No | ||
| top | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/productivity_mcp/server.py:316-329 (handler)The actual handler function for the 'list_recent_senders' tool. It retrieves up to 1000 messages from a folder (default INBOX) within the last N days (default 30), counts messages per sender, and returns the top senders (default 20) sorted by message count descending.
def list_recent_senders( account: str | None = None, folder: str = "INBOX", since_days: int = 30, top: int = 20, ) -> list[dict[str, Any]]: """Top senders over the last N days, ordered by message count. Useful for "who has been emailing me lately?" style questions.""" msgs = _email(account).list_messages(folder=folder, limit=1000, since_days=since_days) counts: dict[str, int] = {} for m in msgs: counts[m.sender] = counts.get(m.sender, 0) + 1 ranked = sorted(counts.items(), key=lambda kv: -kv[1])[:top] return [{"sender": s, "count": c} for s, c in ranked] - src/productivity_mcp/server.py:314-315 (registration)Tool registration via @mcp.tool() decorator on the list_recent_senders function. This is how the tool is registered with the FastMCP server.
@mcp.tool() @_logged - Input schema defined via function signature (account, folder, since_days, top) and return type annotation (list[dict[str, Any]]).
def list_recent_senders( account: str | None = None, folder: str = "INBOX", since_days: int = 30, top: int = 20, ) -> list[dict[str, Any]]: - src/productivity_mcp/server.py:66-73 (helper)The _email() helper function resolves the account name to an EmailProvider instance, used by list_recent_senders to call list_messages().
def _email(account: str | None) -> EmailProvider: if not _email_providers: raise RuntimeError("No email accounts configured. See example.config.toml.") if account is None: return next(iter(_email_providers.values())) if account not in _email_providers: raise KeyError(f"Unknown email account: {account}. Available: {list(_email_providers)}") return _email_providers[account] - The abstract list_messages method on EmailProvider that list_recent_senders calls internally.
def list_messages( self, folder: str = "INBOX", limit: int = 25, query: str | None = None, unread_only: bool = False, recipients: list[str] | None = None, since_days: int | None = None, senders: list[str] | None = None, ) -> list[EmailMessage]: ...