Zapmail

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

---

README truncated. View full README on GitHub.