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

Get your Zapmail API key:
- Sign up at Zapmail
- Navigate to your API settings
- Generate a new API key
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
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

Sign up at Zapmail
Navigate to your API settings
Generate a new API key
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

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
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

Zapmail MCP Server

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

Get your Zapmail API key:
- Sign up at Zapmail
- Navigate to your API settings
- Generate a new API key
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
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

Sign up at Zapmail
Navigate to your API settings
Generate a new API key
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

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
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