@cardor/email-management

Exposes email management operations as MCP server tools that LLM clients can invoke through the ModelContextProtocol standard. Implements the MCP tool schema to define email operations (send, read, delete, etc.) with typed parameters and responses, allowing Claude or other MCP-compatible clients to discover and call email functions via the MCP transport layer without direct API knowledge.

Implements a typed MCP tool that accepts email composition parameters (to, cc, bcc, subject, body, attachments) and executes the send operation through the underlying email provider (SMTP, API, etc.). The tool schema defines strict parameter validation and response formats, ensuring type safety and predictable LLM invocation behavior.

Manages email attachments by validating file types, sizes, and scanning for malware before sending/receiving. Implements attachment extraction from received emails and provides file metadata (filename, MIME type, size) to agents. Supports optional virus scanning integration for security.

Exposes an MCP tool that queries the email inbox/folders with optional filters (sender, subject, date range, read status) and returns paginated results with email metadata (from, to, subject, date, preview). Implements query parameter validation and result formatting to ensure LLM agents receive structured, actionable email data without raw MIME parsing.

Implements MCP tools for destructive email operations (delete, archive, move to folder) with message ID-based targeting and confirmation responses. Includes safety patterns like soft-delete (archive) as the default destructive action and explicit confirmation in tool responses to prevent accidental data loss.

Parses raw email data (MIME, API responses) and normalizes it into a consistent schema (sender, recipient, subject, date, body, attachments) that MCP tools can return. Handles encoding variations, multipart MIME structures, and provider-specific metadata formats to ensure LLM agents receive clean, predictable email data.

Implements a pluggable provider interface that allows swapping between email backends (SMTP, Gmail API, Outlook API, etc.) without changing MCP tool definitions. Each provider implements a common interface (send, retrieve, delete, etc.) and handles provider-specific authentication, rate limiting, and API quirks internally.

Handles secure storage and retrieval of email provider credentials (API keys, OAuth tokens, SMTP passwords) with support for environment variables, encrypted config files, or external secret managers. Implements token refresh logic for OAuth providers and credential validation before tool execution to prevent auth failures mid-operation.

Enforces per-provider rate limits and quota tracking (e.g., Gmail's 100 emails/day limit, API call throttling) by tracking operations and delaying/rejecting requests that would exceed limits. Implements exponential backoff for rate-limited responses and provides quota status in tool responses so agents can adjust behavior.

Optionally exposes email events (new message, read status change, deletion) via webhooks or event streams that external systems can subscribe to. Implements event filtering and routing so agents can react to email changes without polling, enabling real-time email-driven workflows.

Provides optional email template support where agents can reference pre-defined templates with variable substitution (e.g., 'welcome_email' with {{name}}, {{link}} placeholders). Renders templates to final email body before sending, enabling agents to compose complex emails without building HTML/text manually.