Cakemail MCP Server

Gerencie campanhas de email marketing, contatos e emails transacionais com a API Cakemail.

Documentação

Cakemail MCP Server

Um servidor empresarial Model Context Protocol (MCP) para integração com a API do Cakemail. Este servidor fornece ferramentas abrangentes para campanhas de email marketing, emails transacionais, relatórios detalhados, design visual avançado de emails com BEEeditor, gerenciamento de templates e gerenciamento completo de listas por meio da plataforma Cakemail.

🎯 Versão 1.10.0 - Gerenciamento Completo de Templates

Esta versão introduz funcionalidade abrangente de gerenciamento de templates, fornecendo gerenciamento completo do ciclo de vida de templates de email, incluindo criação, atualização, duplicação e recursos avançados de filtragem com suporte a estruturas modernas de conteúdo OpenAPI.

✨ Recursos Atualmente Implementados

🎨 Gerenciamento de Templates (7 ferramentas)

✅ Crie, atualize e exclua templates de email com estrutura de conteúdo moderna
✅ Liste templates com filtragem avançada, ordenação e paginação
✅ Obtenha detalhes e metadados de templates individuais
✅ Duplique templates com nomeação inteligente e preservação de tags
✅ Renderize templates para visualização e teste em HTML
✅ Estrutura de conteúdo compatível com OpenAPI (html, text, bee, custom)
✅ Compatibilidade retroativa com formatos de template legados
✅ Suporte a múltiplas contas para ambientes empresariais
✅ Filtragem avançada por tags, nome e status de propriedade
✅ Busca de templates por nome, tags ou propriedade

👥 Gerenciamento de Contatos

✅ Crie, atualize e exclua contatos com campos personalizados
✅ Liste contatos com filtragem por ID de lista
✅ Suporte avançado à segmentação de contatos
✅ Métricas de engajamento de contatos

📧 Gerenciamento de Campanhas (21 ferramentas)

✅ Crie, atualize e exclua campanhas de email
✅ Liste campanhas com filtragem avançada e paginação
✅ Envie campanhas para listas de contatos
✅ Métricas de desempenho de campanhas (via API de Relatórios)
✅ Obtenha a campanha mais recente com um único comando
✅ Integração com BEEeditor para design visual de emails
✅ Templates de email baseados em JSON com estrutura de arrastar e soltar
✅ Geração de templates de newsletter com layout automatizado
✅ Agendamento de campanhas, suspensão e gerenciamento do ciclo de vida
✅ Teste de campanhas, visualização e histórico de revisões
✅ Arquivamento de campanhas e rastreamento de links

📋 Gerenciamento de Listas (7 ferramentas)

✅ Crie, atualize e exclua listas de contatos
✅ Liste todas as listas com filtragem avançada e paginação
✅ Obtenha informações detalhadas e estatísticas das listas
✅ Arquive listas preservando os dados
✅ Análises abrangentes de desempenho de listas
✅ Suporte a vários idiomas e configuração de remetente
✅ Integração com webhooks para eventos de lista em tempo real
✅ Escopo de conta para ambientes empresariais

📨 Email Transacional (10 ferramentas)

✅ Envie emails transacionais e de marketing individuais
✅ Rastreamento de status de email e monitoramento de entrega
✅ Suporte a conteúdo HTML e texto simples
✅ Recursos de renderização e visualização de emails
✅ Logs abrangentes de atividade de email com filtragem
✅ Estatísticas de email com análises baseadas em tempo
✅ Logs avançados de email com análise de desempenho
✅ Ferramentas de depuração para testes da API de email

🏢 Gerenciamento Empresarial de Subcontas (14 ferramentas)

✅ Crie, atualize e exclua subcontas
✅ Suporte multi-tenant para agências
✅ Suspensão/reativação de contas
✅ Conversão de organizações
✅ Fluxos de verificação de email
✅ Recursos avançados de filtragem e busca
✅ Utilitários de depuração e solução de problemas

📊 Relatórios e Análises Aprimorados (12 ferramentas)

✅ Arquitetura Modular de Relatórios com módulos focados e manuteníveis
✅ Análises de Campanhas com insights detalhados de desempenho e análise de links
✅ Estatísticas da API de Email para desempenho de emails transacionais
✅ Análises de Listas e Contas com métricas de crescimento e saúde de entregabilidade
✅ Benchmarking Inteligente de Desempenho com comparações com padrões do setor
✅ Análise Inteligente de Links com categorização e otimização automáticas
✅ Indicadores Visuais de Desempenho (🚀👍 ⚠️ 🛑) para avaliação rápida
✅ Recomendações Acionáveis com base em padrões de desempenho
✅ Gerenciamento de Exportações com rastreamento de progresso e gerenciamento do ciclo de vida
✅ Exportação de Relatórios de Campanha (CSV/XLSX) com dados abrangentes
✅ Exportação de Emails Suprimidos para conformidade e entregabilidade
✅ Ferramentas de Depuração para testes de conectividade com a API

📋 Logs e Rastreamento de Eventos (6 ferramentas)

✅ Logs de atividade de campanhas com análise avançada de sequência
✅ Logs de automação de fluxos de trabalho
✅ Logs de entrega de emails transacionais
✅ Logs de atividade de listas de contatos
✅ Filtragem inteligente e categorização de eventos
✅ Ferramentas de depuração para testes da API de logs

👤 Gerenciamento de Remetentes (5 ferramentas)

✅ Crie, atualize e exclua remetentes verificados
✅ Liste todos os remetentes com status de verificação
✅ Suporte completo à autenticação de remetentes

🎨 Design Visual BEEeditor (3 ferramentas)

✅ Crie estruturas básicas de templates BEEeditor
✅ Gere templates completos de newsletter com seções
✅ Valide templates JSON BEE em relação ao schema
✅ Recursos de design de email com arrastar e soltar

🏢 Gerenciamento de Conta (2 ferramentas)

✅ Obtenha detalhes e informações da conta atual
✅ Visualize a configuração de repetições e as configurações da API
✅ Monitoramento de saúde da conta e diagnósticos

🏥 Infraestrutura de Produção

✅ Monitoramento de saúde e validação da conexão com a API
✅ Autenticação OAuth 2.0 com renovação automática de token
✅ Lógica de repetição com backoff exponencial
✅ Limitação de taxa e proteção com circuit breaker
✅ Fila de solicitações e controle de concorrência
✅ Tratamento abrangente de erros

Total Implementado: 87+ ferramentas em 11 categorias de recursos

🚀 Início Rápido

Pré-requisitos

Node.js 18 ou superior
Conta Cakemail com acesso à API
Claude Desktop ou outro cliente compatível com MCP

Instalação

Clone o repositório:

git clone https://github.com/cakemail/cakemail-mcp-server.git
cd cakemail-mcp-server

Instale as dependências:

npm install

Compile o projeto:

npm run build

Configuração

Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto:

CAKEMAIL_USERNAME=your-email@example.com
CAKEMAIL_PASSWORD=your-password
CAKEMAIL_BASE_URL=https://api.cakemail.dev

Configuração do Claude Desktop

Adicione o servidor à sua configuração do Claude Desktop:

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

{
  "mcpServers": {
    "cakemail": {
      "command": "node",
      "args": ["/absolute/path/to/cakemail-mcp-server/build/index.js"],
      "env": {
        "CAKEMAIL_USERNAME": "your-email@example.com",
        "CAKEMAIL_PASSWORD": "your-password"
      }
    }
  }
}

🧪 Testes

Teste Rápido

npm run test

Depuração com MCP Inspector

npm run inspector

Verificação de Saúde

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

💡 Exemplos de Uso

Verificação Rápida de Campanha

"Show me my latest campaigns with analytics"

Informações da Conta

"Show me my account details"

"What's my current retry configuration?"

Gerenciamento de Subcontas

"Create a new sub-account for our client 'Acme Corp' with the email admin@acmecorp.com"

"List all active sub-accounts and show their verification status"

"Suspend the sub-account for client XYZ temporarily"

"Convert sub-account 12345 to an organization"

Exemplos de Gerenciamento de Listas

"Create a new contact list called 'Newsletter Subscribers' with our marketing team as the default sender"

"Show me all my contact lists with their subscriber counts"

"Get performance statistics for my main newsletter list"

"Archive the old product launch list but keep the data"

"Update the sender information for my customer list"

Operações com Templates

"List all my email templates sorted by creation date"

"Create a new template called 'Welcome Email' with modern content structure"

"Get the details of template ID 123 including its content and metadata"

"Update my newsletter template with new HTML content and add marketing tags"

"Duplicate the welcome email template as 'Welcome Email - French'"

"Show me a preview of template 456 by rendering it to HTML"

"Delete the old product launch template that's no longer needed"

"Find all templates tagged with 'newsletter' that I own"

Criar e Enviar Campanha

"Create a new email campaign called 'Holiday Sale 2024' with the subject 'Save 50% on Everything!' and send it to my newsletter list"

Templates BEEeditor

"Create a BEE newsletter template with sections for product announcements and customer testimonials"

"Generate a basic BEE template for welcome emails with our brand colors"

"Validate my custom BEE template and show me the structure"

"Create a campaign using BEE format with a professional newsletter layout"

Emails Transacionais

"Send a transactional welcome email to sara@example.com with our onboarding template"

Operações com Listas

"List all my contact lists sorted by creation date"

"Create a contact list for VIP customers with webhook notifications"

"Show me the performance stats for list ID 12345 over the last month"

"Archive all lists that have zero subscribers"

Análises Avançadas e Exportações

"Show me the performance metrics for my latest campaign including open rates and click rates"

"Create a CSV export of all my campaign performance data for the last quarter"

"Get detailed campaign logs for campaign 12345 with advanced sequence analysis to see the complete user journey"

"Analyze campaign 789 logs to identify drop-off points and get optimization recommendations"

"Export the performance data for all my campaigns this year in Excel format"

"Show me link performance analysis for my newsletter campaign with categorization insights"

"Generate performance benchmarks comparing my open rates to industry standards"

Arquitetura do Módulo de Relatórios

A funcionalidade de relatórios é construída sobre uma arquitetura modular para maior manutenibilidade:

Análises de Campanhas: Insights de desempenho, análise de links, métricas de engajamento
Estatísticas de Email: Desempenho de emails transacionais e rastreamento de entrega
Análises de Listas e Contas: Métricas de crescimento, análise de assinantes, saúde da conta
Gerenciamento de Exportações: Ciclo de vida completo de exportação com rastreamento de progresso
Mecanismo de Insights Inteligentes: Análise automatizada de desempenho e recomendações
Utilitários de Depuração: Testes de conectividade com a API e solução de problemas

Cada módulo fornece funcionalidade focada enquanto compartilha utilitários comuns de análise para benchmarking consistente de desempenho e recomendações inteligentes.

🔧 Configuração Avançada

Repetições e Limitação de Taxa

O servidor inclui recursos prontos para produção:

Repetição Automática: Backoff exponencial com jitter
Limitação de Taxa: Respeita os limites da API e as respostas do servidor
Circuit Breaker: Detecção automática de falhas e recuperação
Fila de Solicitações: Controle de concorrência para operações em lote

Tratamento de Erros

Tipos abrangentes de erro com mensagens detalhadas:

Erros de Autenticação: Orientação clara sobre credenciais
Erros de Validação: Detalhes de erro específicos por campo
Erros de Limite de Taxa: Tempo automático de repetição
Erros de Rede: Tratamento de conexão e tempo limite

🐛 Solução de Problemas

Problemas Comuns

Erros de Autenticação:

Verifique CAKEMAIL_USERNAME e CAKEMAIL_PASSWORD
Certifique-se de que o acesso à API está habilitado na sua conta

Erros de Build:

npm run clean && npm run rebuild

Novas Ferramentas Não Aparecem:

Reinicie o Claude Desktop completamente
Aguarde o carregamento completo e teste os novos comandos

Conectividade com a API:

# Test in Claude Desktop
"Check my Cakemail API connection"

Modo de Depuração

DEBUG=mcp:* npm start

🔐 Segurança

Autenticação OAuth 2.0 com renovação automática de token
Validação de entrada para prevenir ataques de injeção
Armazenamento seguro de credenciais usando variáveis de ambiente
Limitação de taxa para prevenir abuso
Comunicação com a API somente via HTTPS

⚠️ Aviso Importante de Segurança

Nunca envie credenciais para o controle de versão! Sempre use variáveis de ambiente para dados sensíveis:

Copie .env.example para .env
Adicione suas credenciais reais a .env
Certifique-se de que .env está listado em .gitignore (já configurado)
Se as credenciais forem expostas acidentalmente, rotacione-as imediatamente na sua conta Cakemail

📚 Suporte

API do Cakemail: https://cakemail.dev
Guia de Gerenciamento de Listas: docs/list-management.md
Integração BEEeditor: docs/BEE_EDITOR_INTEGRATION.md
Protocolo MCP: https://github.com/modelcontextprotocol
Problemas: https://github.com/cakemail/cakemail-mcp-server/issues

📝 Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Pronto para aprimorar seu email marketing com IA? Comece com o Cakemail MCP Server hoje mesmo! 🚀