# Listclean MCP

> Listclean connects your AI agent to a professional email verification API. It checks if emails are real, disposable, or junk in real-time or across large lists. You can use it to validate individual addresses instantly (`verify_single_email`), process up to 3,000 emails at once (`verify_batch_emails`), and check your account status with `check_account_credits`. This tool keeps your contact list clean so your campaigns actually land.

## Overview
- **Category:** marketing-automation
- **Price:** Free
- **Tags:** email-verification, deliverability, data-hygiene, batch-processing, api-validation

## Description

You connect your AI agent to Listclean; it’s basically an email hygiene API that checks if the emails you're sending actually exist. This server lets your agent validate addresses and scrub lists without you ever having to write a single line of verification code. You keep your contact list clean so your campaigns don't bounce off dead ends.

**Processing Email Batches: Scale Your Cleaning Effort**

When you need to check a massive amount of contacts, use the **`verify_batch_emails`** tool. It takes up to 3,000 email addresses in one request and checks them all at once. This is your go-to for processing whole lists before a major send. The server tells you exactly how many emails pass validation versus how many are disposable or junk. You'll get an instant count of the bad apples so you know what to cut out.

**Validate Single Emails: Instant Checks**

Got one address you need to trust? Use **`verify_single_email`**. This tool checks a single email instantly, telling you if it’s valid and giving you an idea of the risk level. It's perfect for validating addresses right inside your workflow as they come in.

**Account Management: Keeping Track of Your Stuff**

Running these tools costs credits, so you gotta know where you stand. Use **`check_account_credits`** to see exactly how many verification credits are left on your account before you start a big job. For general background info, **`get_account_profile`** retrieves the basic details about the Listclean account connected to your agent. If you need to look back at what you’ve already checked, **`get_verification_logs`** pulls a log of every single email address that was previously verified.

**How Your Agent Uses This**

Your AI client handles all the heavy lifting. You just tell your agent, 'Check this list.' The agent knows to call **`verify_batch_emails`**, process the results—saying you’ve got 80% clean emails and 15% that are catch-alls—and report it straight back to you. If you only have one address, the agent calls **`verify_single_email`** so you get an immediate pass/fail status. You never touch the API keys; your agent does the work.

It’s designed for efficiency: The tools keep running in a loop, letting your agent check credits with **`check_account_credits`**, then pulling profile details via **`get_account_profile`** before finally sending the list to **`verify_batch_emails`**. If you need to review the results later, it'll pull those logs using **`get_verification_logs`**, all while making sure every single email address is validated first by **`verify_single_email`** or in bulk through **`verify_batch_emails`**.

## Tools

### verify_batch_emails
Validates multiple email addresses in one request; the maximum size is 3,000 per batch.

### check_account_credits
Checks your remaining verification credits count in Listclean.

### get_verification_logs
Pulls a log of previously verified single email addresses for review.

### get_account_profile
Retrieves general details about the connected Listclean account profile.

### verify_single_email
Checks a single email address instantly to confirm its validity and risk level.

## Prompt Examples

**Prompt:** 
```
Verify the email address 'test@example.com' in Listclean.
```

**Response:** 
```
I've checked the address. 'test@example.com' is marked as 🟢 Clean (valid email). You can safely send to this recipient.
```

**Prompt:** 
```
Show my recent email verification logs.
```

**Response:** 
```
I've retrieved your logs. Your last 5 verifications include addresses from 'gmail.com', 'outlook.com', and a disposable domain. Would you like the full details for any of them?
```

**Prompt:** 
```
How many verification credits do I have left?
```

**Response:** 
```
You currently have 12,450 verification credits remaining in your Listclean account.
```

## Capabilities

### Validate Single Emails
The agent checks one email address instantly to see if it's safe for sending.

### Process Email Batches
You run a large group of emails (up to 3,000) through the tool at once.

### Check Account Credits
The agent tells you exactly how many verification credits are left on your account.

### Get Account Details
You retrieve basic information and profile details associated with the Listclean account.

### Review Validation History
The agent fetches logs showing all previously verified single email addresses.

## Use Cases

### Pre-Sending Campaign Clean-up
A marketer gets a huge list from a trade show. They don't want their campaign bounce rate ruined by bad data. Instead of manually cleaning the spreadsheet, they ask their agent to run `verify_batch_emails` on the whole dump. The agent reports back: 'You can safely send to 78% of this list; filter out the rest.' Problem solved.

### Vet a Single Lead Before Outreach
An SDR gets a prospect's email address from LinkedIn. They aren't sure if it’s real or fake. Instead of guessing, they use `verify_single_email` through their agent. The agent instantly confirms: 'This is Clean (valid email). Go ahead and send the cold outreach.' Immediate action taken.

### Auditing Data Pipelines
A growth engineer needs to prove that all data coming into a new CRM system was clean. They use `get_verification_logs` via their agent, pulling up historical records of validation checks to satisfy the compliance team.

### Checking API Limits
A developer is building an automated reporting tool and needs to make sure they have enough credits for a large test run. They ask the agent to call `check_account_credits` first, avoiding failure mid-script.

## Benefits

- **Stop lost messages.** By using `verify_single_email` before sending a critical email, you ensure the address is active. You cut down on bounce rates instantly.
- **Scale validation without pain.** Instead of running lists through expensive external tools, use `verify_batch_emails`. It processes up to 3,000 emails in one go—fast and efficient.
- **Know your data quality.** The server identifies catch-all or disposable emails. This knowledge lets you filter out garbage addresses before they hurt your sender reputation.
- **Maintain compliance visibility.** Use `get_verification_logs` to build a clear record of who was verified, when, and what the status was. Great for audits.
- **Manage costs easily.** Before running big jobs, always use `check_account_credits` to see your remaining quota. No surprise bills.

## How It Works

The bottom line is: You talk to your AI client in plain English, and it handles connecting to Listclean and getting you structured, accurate results.

1. First, subscribe to the Listclean MCP Server and plug in your API key (X-Auth-Token).
2. Next, ask your AI client to perform a validation task—for example, 'Verify this list of emails.'
3. The agent executes the appropriate tool (`verify_batch_emails` or `verify_single_email`) using your credentials and reports the clean data back.

## Frequently Asked Questions

**How do I use verify_single_email with Listclean MCP Server?**
Just ask your agent to run `verify_single_email` and give it the email address. The agent returns a clear status: 'Clean,' 'Dirty,' or 'Risky.' It's instant validation.

**What is the limit for verify_batch_emails?**
The maximum recommended size for `verify_batch_emails` is 3,000 emails per request. This allows you to handle large list imports efficiently in one call.

**How do I check if I have enough credits with Listclean MCP Server?**
Use the `check_account_credits` tool. The agent will report your current remaining verification quota, so you never run out of service in the middle of a campaign.

**Can get_verification_logs retrieve data for all my emails?**
No; `get_verification_logs` only retrieves logs for previously verified single emails. It's useful for auditing specific, individual checks you ran before.

**How do I set up my account credentials for the Listclean server using get_account_profile?**
You must pass your unique API Key (X-Auth-Token) when initializing the connection. The `get_account_profile` tool validates this key, ensuring your AI client is authorized to run checks and access credit balances.

**What validation statuses does verify_single_email return for bad emails?**
The server returns distinct status flags like 'Disposable,' 'Catch-all,' or 'Risky.' Your AI client reads these specific flags, telling you immediately that the email address is not viable for sending.

**If I use verify_batch_emails too frequently, will there be rate limits?**
Yes, excessive requests can trigger temporary rate limiting. Your agent should detect this and automatically retry the batch operation after a short delay to maintain service continuity.

**What specific data points are tracked when I use get_verification_logs?**
The logs record three key pieces of information: the email checked, the timestamp of the validation, and its final status (Clean, Dirty, or Risky). This lets you audit your entire history.

**What do the statuses 'clean' and 'dirty' mean?**
'Clean' means the email address is valid and safe to send. 'Dirty' means the email is invalid, non-existent, or highly likely to bounce.

**How many emails can I verify at once?**
The `verify_batch_emails` tool supports JSON arrays. It is recommended to keep batches under 3,000 emails per request for optimal performance.

**Where do I find my API Key?**
Log in to your Listclean dashboard and navigate to Account Settings or Profile to find your unique X-Auth-Token.