> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Emailable API reference

> API reference for the Emailable plugin in Corsair: every `emailable.api.*` operation with its input and output types, taken from the plugin's Zod schemas.

> [!NOTE]
>
> **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling).

## Account

### get

`account.get`

Get the credits left on the account. The owner email is not stored.

**Risk:** `read`

```ts theme={null}
await corsair.emailable.api.account.get({});
```

**Input:** *empty object*

`GET /v1/account`. Stores available credits. The owner email is not stored.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `account` | `object` | Yes | — |

> [accordion] account full type
>
> ```ts theme={null}
> {
>   id: account,
>   availableCredits?: number
> }
> ```

***

## Batches

### create

`batches.create`

Start verifying a list of up to 50,000 addresses. Uses one credit per address. Poll batches.get for the results.

**Risk:** `destructive`

```ts theme={null}
await corsair.emailable.api.batches.create({ emails: ['deliverable@example.com', 'risky@example.com'], url: 'https://example.com/emailable-results' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `emails` | `string[]` | Yes | — |
| `url` | `string` | No | HTTPS URL Emailable POSTs the results to when the batch finishes. |
| `responseFields` | `(accept_all \| birth_year \| did_you_mean \| disposable \| domain \| email \| first_name \| free \| full_name \| gender \| last_name \| mailbox_full \| mx_record \| no_reply \| reason \| role \| score \| smtp_provider \| state \| tag \| user)[]` | No | Only return these fields per address. |
| `retries` | `boolean` | No | Retry unclear mail-server answers (default true). Off is faster. |

`POST /v1/batch` with a JSON body. Stores the batch id and message.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `batch` | `object` | Yes | — |

> [accordion] batch full type
>
> ```ts theme={null}
> {
>   id: string,
>   message?: string
> }
> ```

***

### get

`batches.get`

Get a batch: progress, counts per state and reason, and each address's result (up to 1,000 addresses) or a download link (larger batches).

**Risk:** `read`

```ts theme={null}
await corsair.emailable.api.batches.get({ id: '6afc45aa1b2c3d4e5f607182' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `partial` | `boolean` | No | Return results verified so far (batches of up to 1,000 only). |

`GET /v1/batch`. Results per address for batches up to 1,000, a download link above that.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `batch` | `object` | Yes | — |

> [accordion] batch full type
>
> ```ts theme={null}
> {
>   id: string,
>   message?: string,
>   processed?: number,
>   total?: number,
>   done: boolean,
>   emails?: {
>     email?: string,
>     state?: string | null,
>     reason?: string | null,
>     score?: number | null,
>     domain?: string | null,
>     user?: string | null,
>     tag?: string | null,
>     did_you_mean?: string | null,
>     accept_all?: boolean | null,
>     disposable?: boolean | null,
>     free?: boolean | null,
>     role?: boolean | null,
>     no_reply?: boolean | null,
>     mailbox_full?: boolean | null,
>     smtp_provider?: string | null,
>     mx_record?: string | null,
>     duration?: number | null
>   }[],
>   downloadFile?: string,
>   totalCounts?: Record<string, number>,
>   reasonCounts?: Record<string, number>
> }
> ```

***

## Verifications

### verify

`verifications.verify`

Verify one email address: state (deliverable, undeliverable, risky, unknown), reason, score, and flags such as disposable, free, role and accept-all, plus a did-you-mean suggestion. Uses one credit. If `pending` is true, call again within 5 minutes at no extra cost.

**Risk:** `read`

```ts theme={null}
await corsair.emailable.api.verifications.verify({ email: 'deliverable@example.com', smtp: true, timeout: 5 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `email` | `string` | Yes | — |
| `smtp` | `boolean` | No | Run the SMTP check (default true). Off is faster but less accurate. |
| `acceptAll` | `boolean` | No | Also run the accept-all check (default false). Slower. |
| `timeout` | `number` | No | Seconds to wait for a result (2-10, default 5). |

`GET /v1/verify`. Stores the address, state, score, and reason. HTTP 249 returns pending.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `verification` | `object` | No | — |
| `pending` | `boolean` | Yes | True when Emailable is still verifying (HTTP 249). Call again within 5 minutes; repeats in that window are free. |
| `message` | `string` | No | — |

> [accordion] verification full type
>
> ```ts theme={null}
> {
>   email: string,
>   state?: string | null,
>   reason?: string | null,
>   score?: number | null,
>   domain?: string | null,
>   user?: string | null,
>   tag?: string | null,
>   did_you_mean?: string | null,
>   accept_all?: boolean | null,
>   disposable?: boolean | null,
>   free?: boolean | null,
>   role?: boolean | null,
>   no_reply?: boolean | null,
>   mailbox_full?: boolean | null,
>   smtp_provider?: string | null,
>   mx_record?: string | null,
>   duration?: number | null
> }
> ```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.