> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to Listclean

The Listclean connector lets your AI agent act in each user's Listclean account. Each user connects their own Listclean API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 12 tools.

**Authentication:** API Key
**Categories:** Marketing
**Tools:** 12: 9 read, 2 write, 1 destructive
**Users sign in with:** API key
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=LISTCLEAN)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the Listclean connection

   In **AgentKit > Connections**, create a Listclean connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'listclean'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Listclean:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'listclean_account_profile_get',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "listclean"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Listclean:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="listclean_account_profile_get",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their Listclean credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'listclean_account_profile_get',
  toolInput: {},
  connector: 'listclean',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="listclean_account_profile_get",
    tool_input={},
    connection_name="listclean",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `listclean_account_profile_get`

Get Account Profile · Read-only

Get your Listclean account profile.
Returns your name, email, company and billing details.
Use credits_get for the remaining balance.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `listclean_credits_get`

Get Credits · Read-only

Get your remaining Listclean verification credits.
Returns the credit balance.
Each verified address uses one credit.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `listclean_list_get`

Get Email List · Read-only

Get one email list's details.
Returns its name, status, progress and clean, dirty and unknown counts.
Use list_results_get to download its addresses.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `list_id` (`integer`, required): ID of the list (a CSV upload or batch). Get it from lists_list. Example: 1024.

Example input: `{"list_id":1024}`

### `listclean_list_results_get`

Get Email List Results · Read-only

Download the addresses of a finished list that fall in one result type (clean, dirty or unknown), as JSON.
Returns the matching email records with their status details.
Run once per type you need.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `list_id` (`integer`, required): ID of the list (a CSV upload or batch). Get it from lists_list. Example: 1024.
- `type` (`string`, required): A type can be clean, dirty, unknown. Example: clean. One of: `clean`, `dirty`, `unknown`.

Example input: `{"list_id":1024,"type":"clean"}`

### `listclean_lists_list`

List Email Lists · Read-only

List your verified email lists (from CSV uploads and batch verifications).
Returns each list's id, name, status, progress and clean, dirty and unknown counts.
Use list_get for one list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `listclean_upload_get`

Get Upload · Read-only

Get the status of one CSV upload.
Returns its filename, status, chunks received and the list it created.
Use uploads_list to find upload IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `upload_id` (`integer`, required): ID of the upload. Get it from uploads_list. Example: 512.

Example input: `{"upload_id":512}`

### `listclean_uploads_list`

List Uploads · Read-only

List your CSV uploads.
Returns each upload's id, filename, status and chunk progress.
Use upload_get for one upload.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `listclean_verification_analytics_get`

Get Verification Analytics · Read-only

Get email verification totals for a date range, overall and per day.
Returns counts of clean, dirty, unknown and error results.
Use verification_logs_list for individual records.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end_date` (`string`, required): End date of the report range. It cannot be in the future. Example: 2026-11-05.
- `start_date` (`string`, required): Start date of the report range. Example: 2026-11-01.
- `source` (`string`, optional): Optional verification-source filter. Example: api. One of: `api`, `file_upload`, `single_email`.
- `status` (`string`, optional): Optional verification-status filter. Example: clean. One of: `clean`, `dirty`, `unknown`, `error`.

Example input: `{"end_date":"<end_date>","start_date":"<start_date>"}`

### `listclean_verification_logs_list`

List Verification Logs · Read-only

List single-email verification logs over a date range of up to 30 days, with filters and paging.
Returns each log's email, status, source and time.
Use verification_analytics_get for totals.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end_date` (`string`, required): End date of the report range. It cannot be in the future. Example: 2026-11-05.
- `start_date` (`string`, required): Start date of the report range. The maximum date range is 30 days. Example: 2026-11-01.
- `email` (`string`, optional): Optional email-address filter. Example: jane@example.com.
- `limit` (`integer`, optional): Maximum number of log records to return. Defaults to 10. Example: 10.
- `source` (`string`, optional): Optional verification-source filter. Example: api. One of: `api`, `file_upload`, `single_email`.
- `start` (`integer`, optional): Zero-based pagination offset. Defaults to 0. Example: 0.
- `status` (`string`, optional): Optional verification-status filter. Example: clean. One of: `clean`, `dirty`, `unknown`, `error`.

Example input: `{"end_date":"<end_date>","start_date":"<start_date>"}`

### `listclean_email_verify`

Verify Email · Write

Verify one email address. Uses one verification credit.
Returns the address's status (clean, dirty or unknown) and the reasons behind it.
Use emails_verify_batch for many addresses at once.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `email` (`string`, required): The email address to verify. Example: jane@example.com.

Example input: `{"email":"<email>"}`

### `listclean_emails_verify_batch`

Verify Emails in Batch · Write

Submit up to 3,000 email addresses for verification as one list. Uses one credit per address.
Returns the created list's id and status; results are ready when list_get shows it finished.
Use list_results_get to download the clean, dirty or unknown addresses.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `emails` (`array`, required): Email addresses to verify. The default limit is 3,000 addresses per request. Example: ["user1@example.com", "user2@example.com"]
- `filename` (`string`, optional): Optional source filename. If omitted, the API generates a UTC filename in the format batch_upload-DD-MM-YYYY-HHMMSS-utc.csv (for example, batch_upload-05-10-2026-143025-utc.csv). A .csv extension is added when a supplied filename has no extension. Example: october-leads.csv.

Example input: `{"emails":["user1@example.com","user2@example.com"]}`

### `listclean_list_delete`

Delete Email List · Destructive

Delete an email list and its results.
Returns the result.
Download results first if you need them.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `list_id` (`integer`, required): ID of the list (a CSV upload or batch). Get it from lists_list. Example: 1024.

Example input: `{"list_id":1024}`

## Related

Other Marketing connectors ([all 190](/agentkit/connectors/?category=marketing)):

- [HubSpot](/agentkit/connectors/hubspot/): Scalekit connector, OAuth, 457 tools
- [Mailchimp](/agentkit/connectors/mailchimp/): Scalekit connector, OAuth, 73 tools
- [Twitter / X](/agentkit/connectors/twitteroauth/): Scalekit connector, OAuth, 92 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
