---
canonical_url: "https://docs.composio.dev/toolkits/true_list"
markdown_url: "https://docs.composio.dev/toolkits/true_list.md"
product: "platform"
version: null
last_updated: null
---

# TrueList

TrueList validates email addresses, manages batch validation jobs, and retrieves validation history.

- **Category:** email
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 8
- **Triggers:** 0
- **Slug:** `TRUE_LIST`
- **Version:** 00000000_00

## Tools

### Create Batch

**Slug:** `TRUE_LIST_CREATE_BATCH`

Create an asynchronous TrueList batch email-validation job from tabular rows. A successful call consumes validation credits, so use ESTIMATE_BATCH first when cost or row counts are uncertain.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `rows` | array | Yes | Tabular rows for the batch, with a header row first and at least one data row containing an email value. A successful request consumes validation credits. |
| `filename` | string | No | Name shown for the uploaded data and batch. |
| `webhook_url` | string | No | HTTPS callback URL that TrueList should POST the batch ID to when processing completes. |
| `validation_strategy` | string ("accurate" | "fast") | No | Batch validation strategy. fast skips retries; accurate performs the standard validation flow. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Batch

**Slug:** `TRUE_LIST_DELETE_BATCH`

Permanently delete one completed TrueList batch and its validation results. This destructive operation cannot be undone, and TrueList rejects deletion when the batch is missing or has not completed.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `batch_id` | string | Yes | UUID of the completed batch to permanently delete. This removes the batch and its validation results and cannot be undone. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Estimate Batch

**Slug:** `TRUE_LIST_ESTIMATE_BATCH`

Estimate email count, duplicates, and processing time for tabular batch data without creating a batch or consuming batch-validation credits.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `rows` | array | Yes | Tabular rows to estimate, with a header row first and one email value in each data row. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Account

**Slug:** `TRUE_LIST_GET_ACCOUNT`

Return the connected TrueList user identity, account name, and payment plan without exposing API tokens or other account users.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Batch

**Slug:** `TRUE_LIST_GET_BATCH`

Get one TrueList batch-validation job by UUID, including progress counts and completed result download URLs. The provider may return nonterminal states including pending, pending_processing, processing, and finalizing.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `batch_id` | string | Yes | UUID of the batch to retrieve, returned by create or list batches. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Batches

**Slug:** `TRUE_LIST_LIST_BATCHES`

List all batch-validation jobs in the connected TrueList account, including their current processing state, progress counts, and available result download URLs. TrueList returns the complete list without documented pagination.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Validation History

**Slug:** `TRUE_LIST_LIST_VALIDATION_HISTORY`

Return one page of previously validated email results, optionally filtered by batch, address, state, or sub-state.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `email` | string | No | Return history for this exact address as TrueList recorded it, including addresses it marked failed_syntax_check. |
| `batch_id` | string | No | Return only validation results belonging to this batch UUID. |
| `page_size` | integer | No | Maximum results to return in this page (1-100). |
| `email_state` | string ("ok" | "risky" | "invalid" | "unknown") | No | Filter by TrueList's history-filter state. Returned result states may use provider variants such as email_invalid. |
| `next_cursor` | string | No | Continuation cursor returned by the previous call; omit for the first page. |
| `email_sub_state` | string ("email_ok" | "accept_all" | "is_disposable" | "is_role" | "failed_mx_check" | "failed_smtp_check" | "failed_no_mailbox" | "failed_greylisted" | "failed_syntax_check") | No | Filter by the specific validation outcome reason. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Validate Email

**Slug:** `TRUE_LIST_VALIDATE_EMAIL`

Validate one email address synchronously, consume validation capacity, and add the result to TrueList validation history.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `email` | string | Yes | Single email address to validate. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |