Zapmail MCP Server

A Model Context Protocol (MCP) server for the Zapmail API that provides natural language access to domain management, mailbox operations, and exports. This package enables AI assistants like Claude to interact with Zapmail through natural language commands.

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

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"
      }
    }
  }
}

Quick 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"

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

Once connected to your MCP client, you can use natural language to control 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

Variable	Description	Default	Required
ZAPMAIL_API_KEY	Your Zapmail API key	-	Yes
ZAPMAIL_WORKSPACE_KEY	Default workspace ID	-	No
ZAPMAIL_SERVICE_PROVIDER	Email provider (GOOGLE/MICROSOFT)	GOOGLE	No
ZAPMAIL_LOG_LEVEL	Logging level (DEBUG/INFO/WARN/ERROR)	INFO	No
ZAPMAIL_MAX_RETRIES	Maximum retry attempts	3	No
ZAPMAIL_TIMEOUT_MS	Request timeout in milliseconds	30000	No
ZAPMAIL_ENABLE_CACHE	Enable response caching	true	No
ZAPMAIL_ENABLE_METRICS	Enable performance metrics	true	No
ZAPMAIL_RATE_LIMIT_DELAY	Rate limiting delay in ms	1000	No
OPENAI_API_KEY	OpenAI API key for enhanced NLP	-	No

Usage Examples

Domain Operations

Check Domain Availability

In Claude Desktop or Cursor:

"Check if example.com is available for 1 year"

Purchase Domains

In Claude Desktop or Cursor:

"Buy example.com and test.com for 1 year using wallet if possible"

Mailbox Management

Create Mailboxes on Empty Domains

In Claude Desktop or Cursor:

"Create 5 mailboxes on domains that have zero mailboxes"

Bulk Update Mailboxes

In Claude Desktop or Cursor:

"Update all mailboxes with new names and details"

Export Operations

Export to Reachinbox

In Claude Desktop or Cursor:

"Connect my Reachinbox account and export all mailboxes"

Get Export Guidance

In Claude Desktop or Cursor:

"Help me export 100 mailboxes to Reachinbox"

Complex Workflows

Multi-Step Operations

In Claude Desktop or Cursor:

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

Workspace Management

In Claude Desktop or Cursor:

"Show me all my workspaces and switch to the one with the most domains"

System Monitoring

Health Check

In Claude Desktop or Cursor:

"Check the health of my Zapmail connection"

Get Metrics

In Claude Desktop or Cursor:

"Show me performance metrics for my Zapmail operations"

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

Getting Started with MCP

Step 1: Install the Package

Option A: Using npx (Recommended) No installation needed - just use npx:

npx zapmail-mcp

Option B: Global Installation

npm install -g zapmail-mcp

Step 2: Get Your Zapmail API Key

1. Sign up at Zapmail
2. Navigate to your API settings
3. Generate a new API key
4. Note your workspace ID (optional but recommended)

Step 3: Configure Your MCP Client

Choose your preferred MCP client and follow the configuration steps above.

Step 4: Test the Connection

Open your MCP client and try a simple command:

• "List my Zapmail workspaces"
• "Show me my domains"

Step 5: Explore Advanced Features

Once connected, you can:

• Manage domains and mailboxes through natural language
• Export to third-party platforms
• Set up complex automation workflows
• Monitor performance and health

Package Information

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

Command Line Options

The MCP server supports the following 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

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

Contributing

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

License

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

---

Made with ❤️ for the Zapmail community