Zapmail MCP

🚀 Zapmail MCP Server

The Zapmail MCP Server is a Model Context Protocol (MCP) server designed for the Zapmail API. It offers natural - language access to domain management, mailbox operations, and exports. This package allows AI assistants such as Claude to interact with Zapmail using natural language commands.

🚀 Quick Start

Prerequisites

• Node.js 18+
• Zapmail API key
• MCP - compatible client (Claude Desktop, Cursor, etc.)
• Optional: OpenAI API key for enhanced natural language processing

Installation

Option 1: Using npx (Recommended)

No installation required. Run directly with npx:

npx zapmail-mcp

Option 2: Global Installation

Install globally for persistent access:

npm install -g zapmail-mcp

MCP Configuration

For Claude Desktop

Create or update claude_desktop_config.json:

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

Using npx (Recommended):

{
  "mcpServers": {
    "zapmail": {
      "command": "npx",
      "args": ["zapmail-mcp"],
      "env": {
        "ZAPMAIL_API_KEY": "your-zapmail-api-key"
      }
    }
  }
}

Using global installation:

{
  "mcpServers": {
    "zapmail": {
      "command": "zapmail-mcp",
      "args": [],
      "env": {
        "ZAPMAIL_API_KEY": "your-zapmail-api-key"
      }
    }
  }
}

For Cursor

Add to your Cursor MCP settings:

Using npx (Recommended):

{
  "mcpServers": {
    "zapmail": {
      "command": "npx",
      "args": ["zapmail-mcp"],
      "env": {
        "ZAPMAIL_API_KEY": "your-zapmail-api-key"
      }
    }
  }
}

Using global installation:

{
  "mcpServers": {
    "zapmail": {
      "command": "zapmail-mcp",
      "args": [],
      "env": {
        "ZAPMAIL_API_KEY": "your-zapmail-api-key"
      }
    }
  }
}

Steps to Start

1. Get your Zapmail API key:
   • Sign up at Zapmail
   • Navigate to your API settings
   • Generate a new API key
2. Configure your MCP client:
   • Choose your preferred MCP client (Claude Desktop or Cursor)
   • Add the configuration JSON above to your MCP settings
   • Replace your-zapmail-api-key with your actual API key
3. Test the connection:
   • Open your MCP client
   • Try natural language commands like:
     • "List all my Zapmail workspaces"
     • "Show me my domains"
     • "Check if example.com is available for purchase"

✨ Features

• Complete Zapmail API coverage (46+ tools)
• Natural language command processing
• Dynamic tool generation from API documentation
• Export support for Reachinbox, Instantly, Smartlead, Reply.io, and CSV
• Caching system with TTL
• Rate limiting and error handling
• Multi - workspace support
• MCP integration with Claude Desktop and Cursor

💻 Usage Examples

Basic Usage

Once connected to your MCP client, you can use natural language to control Zapmail. Here are some basic examples:

Workspace & Domain Management

"List all my workspaces"

Mailbox Management

"Create 3 mailboxes per domain where there are zero mailboxes"

Export Operations

"Export all mailboxes to reachinbox"

Advanced Usage

Complex Workflows

"Buy example.com and test.com, create 5 mailboxes on each, and export to reachinbox"

System Monitoring

"Show me performance metrics for my Zapmail operations"

📚 Documentation

Available Tools

Core Management Tools

• set_context - Set workspace and provider context
• wallet_balance - Get wallet balance
• list_workspaces - List all workspaces
• list_domains - List domains in workspace
• check_domain_availability - Check domain availability
• purchase_domains - Purchase domains (wallet - first)
• create_mailboxes_for_zero_domains - Create mailboxes on empty domains
• add_third_party_account - Add third - party export account
• call_endpoint - Call any Zapmail endpoint
• generate_usernames - Generate mailbox usernames
• generate_name_pairs - Generate name pairs
• generate_domains - Generate AI - powered domain suggestions
• check_domain_availability_batch - Batch domain availability check
• plan_and_execute - Natural - language plan & execute
• get_server_info - Get server information

System Management Tools

• get_metrics - Get system metrics and performance data
• clear_cache - Clear system cache
• health_check - System health check

Advanced Mailbox Tools

• bulk_update_mailboxes - Bulk update mailboxes
• search_mailboxes - Search mailboxes with advanced filters

Export System Tools

• get_export_info - Get export system information
• get_export_scenario - Get export scenario instructions
• validate_export_request - Validate export request parameters
• export_guidance - Get export guidance and best practices

API Documentation Tools

• get_api_info - Get comprehensive API endpoint information
• search_api_endpoints - Search API endpoints by keyword
• get_api_scenarios - Get common API usage scenarios
• get_api_best_practices - Get API best practices and recommendations
• generate_api_examples - Generate API usage examples

Dynamic API Tools

All documented API endpoints with automatic tool generation

Natural Language Commands

You can use natural language to manage different aspects of Zapmail:

Workspace & Domain Management

• "List all my workspaces"
• "Show domains in current workspace containing 'lead'"
• "Check if leadconnectlab.com is available for 2 years"
• "Buy leadconnectlab.com and outreachprohub.com for 1 year using wallet if possible"

Mailbox Management

• "Create 3 mailboxes per domain where there are zero mailboxes"
• "Setup 100 mailboxes and connect to Instantly.ai for me"
• "Update all mailboxes with new names"

Export Operations

• "Export all mailboxes to reachinbox"
• "Export mailboxes to instantly"
• "Export mailboxes as CSV"
• "Export specific mailboxes"
• "Export mailboxes from leadconnectio.com domain"

Third - Party Integration

• "Connect reachinbox account"
• "Add instantly credentials"
• "Link smartlead account"
• "Setup reply.io integration"

Configuration

Environment Variables

🔧 Technical Details

The Zapmail MCP Server is built to provide seamless natural - language interaction with the Zapmail API. It uses Node.js as the runtime environment and supports various features such as caching, rate - limiting, and error handling. The dynamic tool generation feature allows for easy access to all documented API endpoints.

📄 License

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

📦 Package Information

• Package Name: zapmail-mcp
• Version: 0.0.2
• NPM: zapmail-mcp
• GitHub: dsouzaalan/zapmail-mcp

🛠️ Troubleshooting

MCP Connection Issues

1. MCP Server Not Found

Problem: "zapmail-mcp command not found" or "npx zapmail-mcp not found" Solutions:

For npx usage:

# Test npx directly
npx zapmail-mcp --version

# If npx fails, try with explicit package version
npx zapmail-mcp@latest --version

# Get help information
npx zapmail-mcp --help

For global installation:

# Install the package globally
npm install -g zapmail-mcp

# Verify installation
zapmail-mcp --version

2. MCP Client Not Detecting Server

Problem: Zapmail tools not appearing in Claude Desktop/Cursor Solutions:

• Restart your MCP client (Claude Desktop/Cursor)
• Check your MCP configuration file syntax
• Verify the command path in your config

3. API Key Issues

Problem: "ZAPMAIL_API_KEY not configured" Solutions:

• Set environment variable in your MCP config:

{
  "mcpServers": {
    "zapmail": {
      "command": "npx",
      "args": ["zapmail-mcp"],
      "env": {
        "ZAPMAIL_API_KEY": "your-api-key"
      }
    }
  }
}

• Or set globally:

export ZAPMAIL_API_KEY="your-api-key"

4. Workspace Context Issues

Problem: Getting data from wrong workspace Solution: Set workspace in MCP config:

{
  "env": {
    "ZAPMAIL_WORKSPACE_KEY": "your-workspace-id"
  }
}

Performance Issues

1. Slow Response Times

Problem: MCP operations taking too long Solutions:

• Enable caching: ZAPMAIL_ENABLE_CACHE="true"
• Increase rate limit delay: ZAPMAIL_RATE_LIMIT_DELAY="2000"
• Check your internet connection

2. Rate Limiting

Problem: "Too many requests" errors Solution: Increase rate limit delay in MCP config:

{
  "env": {
    "ZAPMAIL_RATE_LIMIT_DELAY": "2000"
  }
}

Debug Mode

Enable debug logging for detailed troubleshooting:

{
  "env": {
    "ZAPMAIL_LOG_LEVEL": "DEBUG"
  }
}

Health Check

Test your MCP connection: In Claude Desktop or Cursor:

"Check the health of my Zapmail connection"

Common MCP Configuration Errors

1. Invalid JSON Syntax

Problem: MCP client fails to load configuration Solution: Validate your JSON configuration using a JSON validator

2. Wrong Command Path

Problem: "Command not found" in MCP client Solution: Use full path or ensure zapmail-mcp is in your PATH

3. Environment Variables Not Loading

Problem: API key not being passed to MCP server Solution: Use the env section in your MCP configuration instead of global environment variables

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📞 Support

For support and questions:

• Check the troubleshooting section above
• Review the MCP configuration examples
• Test your connection with health checks
• Enable debug logging for detailed error information
• Visit the GitHub repository for issues and discussions

⌨️ Command Line Options

Version Information

npx zapmail-mcp --version
# or
npx zapmail-mcp -v

Help Information

npx zapmail-mcp --help
# or
npx zapmail-mcp -h

Made with ❤️ for the Zapmail community