Send an email via specified email service.

Sends an email using the specified email service. Supports SMTP, API-based services, local testing services, and webhook integrations. Automatically detects service capabilities and uses the appropriate sending method.

Args: to: Recipient email address(es). Can be: - Single address: "user@example.com" - Comma-separated: "user1@example.com, user2@example.com" - List: ["user1@example.com", "user2@example.com"] subject: Email subject line. Required. body: Plain text email body. Required. This serves as the fallback for email clients that don't support HTML. service: Email service to use. Options: - "default": Default SMTP/IMAP service (from env vars) - "sendgrid": SendGrid transactional email - "mailgun": Mailgun transactional email - "resend": Resend transactional email - "mailhog": Local MailHog testing service - "slack": Send to Slack webhook - "discord": Send to Discord webhook - Custom service names configured via EMAIL_SERVICES html: Optional HTML email body. If provided, the email will be sent as multipart/alternative with both text and HTML versions. Example: "TitleContent" cc: Optional CC (carbon copy) recipients. Same format as 'to'. bcc: Optional BCC (blind carbon copy) recipients. Same format as 'to'.

Returns: Dictionary with service-specific results: { "success": bool, # True if email sent successfully "status": str, # "sent" on success "service": str, # Service used "to": str, # Recipient address(es) "subject": str, # Email subject "error": str # Error message if success is False }

Examples: # Send via default SMTP service send_email( to="user@example.com", subject="Hello", body="This is a test email" )

# Send via SendGrid
send_email(
    to="user@example.com",
    subject="Welcome",
    body="Welcome to our service",
    service="sendgrid",
    html="<h1>Welcome!</h1><p>Thanks for joining.</p>"
)

# Send to Slack webhook
send_email(
    to="general",
    subject="Alert",
    body="System alert message",
    service="slack"
)

Notes: - Service availability depends on configuration - API services may have different rate limits and features - Local testing services don't send real emails - Webhook services convert emails to chat messages

Check inbox via specified email service.

Retrieves emails from the specified service and folder. Supports IMAP-based services, local testing services with web APIs, and service-specific inbox checking.

Args: service: Email service to check. Options: - "default": Default IMAP service (from env vars) - "mailhog": Local MailHog testing service - "mailpit": Local Mailpit testing service - Custom service names that support inbox checking folder: Mail folder name to check. Default: "INBOX". Common folders: - "INBOX": Main inbox folder - "Sent": Sent items folder - "Drafts": Draft messages folder - "Trash": Deleted messages folder Folder names are case-sensitive and provider-specific. limit: Maximum number of emails to return. Default: 10. unread_only: If True, only returns unread emails. Default: False. from_contains: Optional case-insensitive substring filter on From (IMAP scans recent mail). subject_contains: Optional case-insensitive substring filter on Subject.

Returns: Dictionary with service-specific results: { "success": bool, # True if inbox check succeeded "emails": [ # List of email dictionaries { "id": str, # Message ID "subject": str, # Email subject "from": str, # Sender address "date": str, # Email date "read": bool # Read status } ], "count": int, # Number of emails returned "service": str, # Service used "folder": str, # Folder checked "error": str # Error message if success is False }

Examples: # Check default IMAP inbox check_inbox() # Returns: {"success": True, "emails": [...], "count": 10, "service": "default"}

# Check MailHog testing inbox
check_inbox(service="mailhog", limit=20)
# Returns emails from local testing service

# Check unread emails only
check_inbox(unread_only=True, limit=5)

Notes: - Not all services support inbox checking (API/webhook services typically don't) - Local testing services provide web UIs for viewing emails - IMAP services support standard folder names - Results are sorted with most recent first

MAILING_LISTS_CATALOG — List named mailing-list presets from EMAIL_MCP_MAILING_LISTS (JSON).

Configure labels/folders once (e.g. Gmail filter → IMAP folder), then use mailing_list_latest(id).

Returns: success, entries[] with id, service, folder, limit, unread_only, from_contains, subject_contains; or error if unset/invalid JSON.

MAILING_LIST_LATEST — Fetch newest messages for a preset id (see mailing_lists_catalog).

Loads folder/service/filters from EMAIL_MCP_MAILING_LISTS. Typical use: newsletter drops in a dedicated IMAP folder (Alpha Signal, etc.). Optional limit/unread_only override entry defaults.

Args: list_id: Preset id from catalog (e.g. alphasignal). limit: Override max messages (default: from preset, usually 5). unread_only: Override UNSEEN-only (default: from preset, usually True for newest drop).

Returns: Same shape as check_inbox plus list_id and preset fields.

Get email service status and test connectivity.

Tests connectivity for specified service or all configured services. Verifies that credentials are correct and services are reachable.

Args: service: Specific service to test, or None for all services.

Returns: Dictionary with service status information: { "server": str, # Server name "version": str, # Server version "services": { # Service-specific status "service_name": { "configured": bool, "connected": bool, "error": str, # Error message if connection failed "type": str # Service type (smtp, api, local, webhook) } }, "total_services": int, "configured_services": int, "connected_services": int }

Examples: # Check all services email_status() # Returns status for all configured services

# Check specific service
email_status(service="sendgrid")
# Returns status only for SendGrid service

Notes: - Tests actual connectivity, not just configuration presence - Connection tests are quick (timeout after 5-10 seconds) - API keys and passwords are not exposed in results

Configure a new email service dynamically.

Adds a new email service configuration at runtime. The service will be available for sending emails and inbox checking immediately.

Args: name: Unique name for the service (e.g., "my-sendgrid", "dev-mailhog") type: Service type - "smtp", "api", "local", or "webhook" config: Service-specific configuration dictionary enabled: Whether the service should be enabled (default: True)

Returns: Dictionary with configuration result: { "success": bool, "service": str, # Service name "type": str, # Service type "message": str # Success/error message }

Examples: # Configure SendGrid API service configure_service( name="my-sendgrid", type="api", config={ "api_key": "your-sendgrid-key", "api_url": "https://api.sendgrid.com/v3/mail/send", "from_email": "noreply@yourdomain.com", "service_type": "sendgrid" } )

# Configure local MailHog for testing
configure_service(
    name="local-testing",
    type="local",
    config={
        "smtp_server": "localhost",
        "smtp_port": 1025,
        "http_url": "http://localhost:8025",
        "service_type": "mailhog"
    }
)

Notes: - Service names must be unique - Configuration is stored in memory (not persisted) - Use list_services() to see available services

List all configured email services.

Returns information about all available email services, their types, and configuration status.

Returns: Dictionary with service information: { "services": { "service_name": { "type": str, # Service type "enabled": bool, # Whether service is enabled "configured": bool, # Whether properly configured "description": str # Human-readable description } }, "count": int, # Total number of services "enabled_count": int, # Number of enabled services "types": [str] # List of available service types }

Examples: # List all services list_services() # Returns: { # "services": { # "default": {"type": "smtp", "enabled": true, "configured": true, "description": "Default SMTP/IMAP service"}, # "sendgrid": {"type": "api", "enabled": true, "configured": true, "description": "SendGrid transactional email"} # }, # "count": 2, # "enabled_count": 2, # "types": ["smtp", "api", "local", "webhook"] # }

Notes: - Shows both automatically configured and manually added services - Configuration status indicates if required credentials are available - Use email_status() to test actual connectivity

Get help and usage information for email MCP tools and services.

Returns comprehensive help information including available tools, supported services, usage examples, configuration requirements, and common use cases.

Returns: Dictionary with service and tool information: { "server": str, # Server name "version": str, # Server version "description": str, # Server description "supported_services": { # Available service types "smtp": str, # Description of SMTP services "api": str, # Description of API services "local": str, # Description of local services "webhook": str # Description of webhook services }, "tools": [...], # List of available tools "examples": [...], # Usage examples "notes": [...] # Important notes and tips }

Examples: # Get comprehensive help email_help() # Returns full documentation for all services and tools

Notes: - Use list_services() to see currently configured services - Use email_status() to test service connectivity - Use configure_service() to add new services dynamically

Suggest 1–3 concise email subject lines for the given body (uses MCP sampling when available).

Plan a short multi-step email workflow using sampling (agentic assist).

Uses the host LLM via sampling when available; optional Anthropic fallback if configured.