Cakemail MCP Server

An enterprise Model Context Protocol (MCP) server for integrating with the Cakemail API. This server provides comprehensive tools for email marketing campaigns, transactional emails, detailed reporting, advanced BEEeditor visual email design, template management, and complete list management through the Cakemail platform.

🎯 Version 1.10.0 - Complete Template Management

This version introduces comprehensive template management functionality, providing complete lifecycle management for email templates including creation, updating, duplication, and advanced filtering capabilities with support for modern OpenAPI content structures.

✨ Currently Implemented Features

🎨 Template Management (7 tools)

• ✅ Create, update, and delete email templates with modern content structure

• ✅ List templates with advanced filtering, sorting, and pagination

• ✅ Get individual template details and metadata

• ✅ Duplicate templates with smart naming and tag preservation

• ✅ Render templates for HTML preview and testing

• ✅ OpenAPI-compliant content structure (html, text, bee, custom)

• ✅ Backward compatibility with legacy template formats

• ✅ Multi-account support for enterprise environments

• ✅ Advanced filtering by tags, name, ownership status

• ✅ Template search by name, tags, or ownership

👥 Contact Management

• ✅ Create, update, and delete contacts with custom fields

• ✅ List contacts with filtering by list ID

• ✅ Advanced contact segmentation support

• ✅ Contact engagement metrics

📧 Campaign Management (21 tools)

• ✅ Create, update, and delete email campaigns

• ✅ List campaigns with advanced filtering and pagination

• ✅ Send campaigns to contact lists

• ✅ Campaign performance metrics (via Reports API)

• ✅ Get latest campaign with one command

• ✅ BEEeditor integration for visual email design

• ✅ JSON-based email templates with drag-and-drop structure

• ✅ Newsletter template generation with automated layout

• ✅ Campaign scheduling, suspension, and lifecycle management

• ✅ Campaign testing, preview, and revision history

• ✅ Campaign archiving and link tracking

📋 List Management (7 tools)

• ✅ Create, update, and delete contact lists

• ✅ List all lists with advanced filtering and pagination

• ✅ Get detailed list information and statistics

• ✅ Archive lists while preserving data

• ✅ Comprehensive list performance analytics

• ✅ Multi-language support and sender configuration

• ✅ Webhook integration for real-time list events

• ✅ Account scoping for enterprise environments

📨 Transactional Email (10 tools)

• ✅ Send individual transactional and marketing emails

• ✅ Email status tracking and delivery monitoring

• ✅ HTML and plain text content support

• ✅ Email rendering and preview capabilities

• ✅ Comprehensive email activity logs with filtering

• ✅ Email statistics with time-based analytics

• ✅ Advanced email logs with performance analysis

• ✅ Debug tools for email API testing

🏢 Enterprise Sub-Account Management (14 tools)

• ✅ Create, update, and delete sub-accounts

• ✅ Multi-tenant support for agencies

• ✅ Account suspension/unsuspension

• ✅ Organization conversion

• ✅ Email verification workflows

• ✅ Advanced filtering and search capabilities

• ✅ Debug and troubleshooting utilities

📊 Enhanced Reporting & Analytics (12 tools)

• ✅ Modular Reports Architecture with focused, maintainable modules

• ✅ Campaign Analytics with detailed performance insights and link analysis

• ✅ Email API Statistics for transactional email performance

• ✅ List & Account Analytics with growth metrics and deliverability health

• ✅ Smart Performance Benchmarking with industry standard comparisons

• ✅ Intelligent Link Analysis with automatic categorization and optimization

• ✅ Visual Performance Indicators (🚀👍⚠️🛑) for quick assessment

• ✅ Actionable Recommendations based on performance patterns

• ✅ Export Management with progress tracking and lifecycle management

• ✅ Campaign Reports Export (CSV/XLSX) with comprehensive data

• ✅ Suppressed Emails Export for compliance and deliverability

• ✅ Debug Tools for API connectivity testing

📋 Logs & Event Tracking (6 tools)

• ✅ Campaign activity logs with advanced sequence analysis

• ✅ Workflow automation logs

• ✅ Transactional email delivery logs

• ✅ Contact list activity logs

• ✅ Smart filtering and event categorization

• ✅ Debug tools for logs API testing

👤 Sender Management (5 tools)

• ✅ Create, update, and delete verified senders

• ✅ List all senders with verification status

• ✅ Complete sender authentication support

🎨 BEEeditor Visual Design (3 tools)

• ✅ Create basic BEEeditor template structures

• ✅ Generate complete newsletter templates with sections

• ✅ Validate BEE JSON templates against schema

• ✅ Drag-and-drop email design capabilities

🏢 Account Management (2 tools)

• ✅ Get current account details and information

• ✅ View retry configuration and API settings

• ✅ Account health monitoring and diagnostics

🏥 Production Infrastructure

• ✅ Health monitoring and API connection validation

• ✅ OAuth 2.0 authentication with automatic token refresh

• ✅ Retry logic with exponential backoff

• ✅ Rate limiting and circuit breaker protection

• ✅ Request queuing and concurrency control

• ✅ Comprehensive error handling

Total Implemented: 87+ tools across 11 feature categories

🚀 Quick Start

Prerequisites

• Node.js 18 or higher

• Cakemail account with API access

• Claude Desktop or another MCP-compatible client

Installation

1. Clone the repository:

2. Install dependencies:

3. Build the project:

Configuration

Environment Variables

Create a .env file in the project root:

Claude Desktop Setup

Add the server to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

🧪 Testing

Quick Test

Debug with MCP Inspector

Health Check

In Claude Desktop: "Check my Cakemail API health status"

💡 Usage Examples

Quick Campaign Check

Account Information

Sub-Account Management

List Management Examples

Template Operations

Create and Send Campaign

BEEeditor Templates

Transactional Emails

List Operations

Advanced Analytics & Exports

Reports Module Architecture

The reports functionality is built on a modular architecture for enhanced maintainability:

• Campaign Analytics: Performance insights, link analysis, engagement metrics

• Email Statistics: Transactional email performance and delivery tracking

• List & Account Analytics: Growth metrics, subscriber analysis, account health

• Export Management: Complete export lifecycle with progress tracking

• Smart Insights Engine: Automated performance analysis and recommendations

• Debug Utilities: API connectivity testing and troubleshooting

Each module provides focused functionality while sharing common analytics utilities for consistent performance benchmarking and intelligent recommendations.

🔧 Advanced Configuration

Retry and Rate Limiting

The server includes production-ready features:

• Automatic Retry: Exponential backoff with jitter

• Rate Limiting: Respects API limits and server responses

• Circuit Breaker: Automatic failure detection and recovery

• Request Queuing: Concurrency control for batch operations

Error Handling

Comprehensive error types with detailed messages:

• Authentication Errors: Clear credential guidance

• Validation Errors: Field-specific error details

• Rate Limit Errors: Automatic retry timing

• Network Errors: Connection and timeout handling

🐛 Troubleshooting

Common Issues

Authentication Errors:

• Verify CAKEMAIL_USERNAME and CAKEMAIL_PASSWORD

• Ensure API access is enabled on your account

Build Errors:

New Tools Not Showing:

• Restart Claude Desktop completely

• Wait for full load, then test new commands

API Connectivity:

Debug Mode

🔐 Security

• OAuth 2.0 authentication with automatic token refresh

• Input validation to prevent injection attacks

• Secure credential storage using environment variables

• Rate limiting to prevent abuse

• HTTPS-only API communication

⚠️ Important Security Notice

Never commit credentials to version control! Always use environment variables for sensitive data:

1. Copy .env.example to .env

2. Add your actual credentials to .env

3. Ensure .env is listed in .gitignore (already configured)

4. If credentials are accidentally exposed, rotate them immediately in your Cakemail account

📚 Support

• Cakemail API: https://cakemail.dev

• List Management Guide: docs/list-management.md

• BEEeditor Integration: docs/BEE_EDITOR_INTEGRATION.md

• MCP Protocol: https://github.com/modelcontextprotocol

• Issues: https://github.com/cakemail/cakemail-mcp-server/issues

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

Ready to enhance your email marketing with AI? Get started with the Cakemail MCP Server today! 🚀