# Listclean — how to use (mcp.ai)

Connect your Listclean account and use 16 tools for email straight from your AI agent. Connect with your own API key. Listclean is an email verification service that helps users validate and clean their email lists to improve deliverability and maintain sender reputation.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_listclean?ms=1787293440000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `listclean_create_bulk_verification_list`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/listclean`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/listclean/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/listclean/create/bulk/verification/list` — Tool to create a CSV file with provided email addresses for bulk verification. Use when you need to generate a file for bulk upload through LISTCLEAN_UPLOAD_LIST.
  - body: { emails: string[] }
- `POST https://api.mcp.ai/api/listclean/delete/list` — Tool to permanently delete a single list from the account. Use when you need to remove a list that is no longer needed.
  - body: { list_id: integer }
- `POST https://api.mcp.ai/api/listclean/download/csv` — Tool to download list results as a CSV file. Use when you need to retrieve verification results filtered by email type (clean, dirty, or unknown).
  - body: { type: string, list_id: integer }
- `POST https://api.mcp.ai/api/listclean/download/json` — Tool to download list results as JSON. Downloads emails filtered by type (clean, dirty, or unknown) in JSON format. Use after list verification is complete to retrieve filtered results.
  - body: { type: string, list_id: integer }
- `POST https://api.mcp.ai/api/listclean/get/account/profile` — Tool to retrieve the authenticated account's profile. Use after obtaining a valid auth token to fetch user account data.
- `POST https://api.mcp.ai/api/listclean/get/credits` — Tool to retrieve remaining verification credits. Use when you need to check your available account credits before performing more email verifications.
- `POST https://api.mcp.ai/api/listclean/get/list` — Tool to retrieve detailed information for a specific list. Returns analytics with clean/dirty breakdown, cost details, and processing status.
  - body: { list_id: integer }
- `POST https://api.mcp.ai/api/listclean/get/upload/status` — Tool to retrieve the status of a specific upload. Returns upload status (inprocess, success, error), progress percentage, and chunk details. Use after initiating an upload to track its completion.
  - body: { upload_id: integer }
- `POST https://api.mcp.ai/api/listclean/get/verification/logs` — Tool to retrieve logs for all single email verifications. Returns history of email verifications with status, remarks, credits deducted, and timestamps.
  - body: { start?: integer, length?: integer }
- `POST https://api.mcp.ai/api/listclean/list/all` — Tool to retrieve all email verification lists. Returns all processed lists with complete analytics including clean/dirty counts, summary statistics, and cost information.
- `POST https://api.mcp.ai/api/listclean/list/uploads` — Tool to retrieve the list of CSV uploads. Use when you need to check upload IDs, status, and progress for all CSV file uploads in your account.
  - body: { start?: integer, length?: integer }
- `POST https://api.mcp.ai/api/listclean/start/upload` — Tool to start a CSV upload process for bulk email verification. Initializes chunked file upload and returns an upload_id for subsequent chunk uploads. Use when you need to upload large CSV files conta
  - body: { filename: string, file_type: string, escape_char?: string, fast_process?: integer, enclosure_char?: string, max_chunk_size: integer, separator_char?: string, total_chunk_count: integer, email_column_index: integer }
- `POST https://api.mcp.ai/api/listclean/update/profile` — Tool to update account profile details. Use when you need to modify user profile information such as name, address, contact details, company information, or billing details.
  - body: { city?: string, name?: string, address?: string, country?: string, website?: string, linkedin?: string, skype_id?: string, billing_name?: string, company_name?: string, phone_number?: string, twitter_handle?: string, billing_address?: string, billing_company_name?: string }
- `POST https://api.mcp.ai/api/listclean/upload/chunk` — Tool to upload a chunk of a CSV file. Use when sending base64-encoded content with sequence number as part of chunked upload process, optionally with MD5 checksum for integrity verification.
  - body: { content: string, upload_id: integer, md5_checksum?: string, chunk_sequence_number: integer }
- `POST https://api.mcp.ai/api/listclean/verify/batch` — Tool to verify a batch of email addresses (max 3000 emails). Use when you need to verify multiple emails at once and get a list_id for tracking the batch verification request.
  - body: { emails: string[] }
- `POST https://api.mcp.ai/api/listclean/verify/email` — Tool to verify an email's validity. Use when you need to ensure an address is deliverable and non-disposable, after collecting a user's email.
  - body: { email: string }

## Example prompts
- "What can I do in Listclean?"
- "Show me a summary of my Listclean account"

## More
- Page: https://mcp.ai/listclean
- Agent spec (llms.txt): https://mcp.ai/listclean/llms.txt
- Postman collection: https://mcp.ai/listclean/postman.json