# AtData SafeToSend MCP Server


A Model Context Protocol (MCP) server that provides email verification services using AtData's SafeToSend API. This server allows you to verify email addresses to filter out invalid and high-risk ones, resulting in higher open rates, clicks, and conversions.

<a href="https://glama.ai/mcp/servers/@avivshafir/atdata-email-verification-mcp-server">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@avivshafir/atdata-email-verification-mcp-server/badge" alt="atdata-email-verification-mcp-server MCP server" />
</a>

https://docs.atdata.com/reference/safe-to-send

## Features

- **Email Verification**: Verify individual email addresses using AtData's SafeToSend API 
- **Batch Verification**: Verify multiple email addresses at once with summary statistics
- **Comprehensive Error Handling**: Detailed error messages for different failure scenarios
- **Environment Variable Support**: Secure API key management through environment variables
- **Rate Limiting Awareness**: Proper handling of API rate limits

## Installation

1. Clone this repository:
```bash
git clone <repository-url>
cd atdata-mcp-server
```

2. Install dependencies using uv (recommended) or pip:
```bash
# Using uv
uv sync

# Using pip
uv pip install .
```

## Setup

### Get AtData API Key

1. Sign up for an AtData account at [https://atdata.com](https://atdata.com)
2. Obtain your API key from the AtData dashboard
3. Set up your API key as an environment variable:

```bash
export ATDATA_API_KEY="your-api-key-here"
```

Or create a `.env` file in the project root:
```
ATDATA_API_KEY=your-api-key-here
```

## Usage

### Running the Server

#### Method 1: Direct Python execution
```bash
python server.py
```

#### Method 2: Using FastMCP CLI
```bash
fastmcp run server.py
```

#### Method 3: Install for Claude Desktop
```bash
fastmcp install server.py
```

#### Using with uv

If you're using uv, you can also run the server with:

```json
{
  "mcpServers": {
    "atdata-email-verification-mcp-server": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "/path/to/your/atdata-email-verification-mcp-server",
      "env": {
        "ATDATA_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### Available Tools

#### 1. `verify_email`
Verify a single email address.

**Parameters:**
- `email` (string, required): The email address to verify
- `api_key` (string, optional): AtData API key (uses environment variable if not provided)

**Example:**
```python
{
    "email": "user@example.com",
    "api_key": "your-api-key"  # Optional if ATDATA_API_KEY is set
}
```

**Response:**
```python
{
    "success": True,
    "email": "user@example.com",
    "verification_result": {
        "email": "user@example.com",
        "status": "valid",
        "deliverable": True,
        "risk_level": "low",
        # Additional verification details from AtData API
    }
}
```

#### 2. `batch_verify_emails`
Verify multiple email addresses in batch.

**Parameters:**
- `emails` (array of strings, required): List of email addresses to verify
- `api_key` (string, optional): AtData API key (uses environment variable if not provided)

**Example:**
```python
{
    "emails": ["user1@example.com", "user2@domain.com", "invalid@email"],
    "api_key": "your-api-key"  # Optional if ATDATA_API_KEY is set
}
```

**Response:**
```python
{
    "results": [
        {
            "success": True,
            "email": "user1@example.com",
            "verification_result": { /* verification details */ }
        },
        {
            "success": True,
            "email": "user2@domain.com", 
            "verification_result": { /* verification details */ }
        },
        {
            "error": "Bad request. Please check the email format.",
            "email": "invalid@email",
            "status_code": 400
        }
    ],
    "summary": {
        "total": 3,
        "successful": 2,
        "failed": 1,
        "success_rate": 66.67
    }
}
```

## Error Handling

The server provides comprehensive error handling for various scenarios:

- **Missing API Key**: Returns error when no API key is provided
- **Authentication Errors**: Handles invalid API keys (401 status)
- **Bad Requests**: Handles invalid email formats (400 status)
- **Rate Limiting**: Handles API rate limit exceeded (429 status)
- **Network Issues**: Handles connection errors and timeouts
- **Unexpected Errors**: Catches and reports any unexpected exceptions

## API Documentation

This server is based on the AtData SafeToSend API. For more details about the underlying API, see:
- [AtData SafeToSend API Documentation](https://docs.atdata.com/reference/safe-to-send)

## Development

### Project Structure
```
atdata-mcp-server/
├── src/
│   └── server.py          # Main MCP server implementation
├── pyproject.toml         # Project configuration and dependencies
├── uv.lock               # Locked dependencies
└── README.md             # This file
```

## 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.

## Support

For issues related to:
- **This MCP Server**: Open an issue in this repository
- **AtData API**: Contact AtData support or check their documentation
- **FastMCP Framework**: Check the [FastMCP documentation](https://github.com/jlowin/fastmcp)