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

# Validate

> Check whether a mailbox is real and whether a domain is live.

`POST /v1/validate` answers: is this mailbox real, and is this company domain live? Send one email, a list of emails, a domain, or a mix. Use it before sending to addresses you already have.

```bash curl theme={null}
curl -X POST https://YOUR_AGENTIC_ID_HOST/v1/validate \
  -H "Authorization: Bearer $AGENTIC_ID_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3e1a9c57-4b02-4f6d-8a11-7c9e5d2b6f04" \
  -d '{
    "emails": ["alex.rivera@acme.example", "info@acme.example"],
    "domain": "acme.example",
    "max_credits": 2
  }'
```

```typescript TypeScript theme={null}
import { AgenticId } from '@ic/agentic-id-sdk';

const client = new AgenticId({
  apiKey: process.env.AGENTIC_ID_API_KEY,
  baseUrl: 'https://YOUR_AGENTIC_ID_HOST',
});

const reply = await client.validate({
  emails: ['alex.rivera@acme.example', 'info@acme.example'],
  domain: 'acme.example',
  max_credits: 2,
});
for (const r of reply.results) console.log(r.email, r.verdict);
```

```bash CLI theme={null}
agentic-id validate alex.rivera@acme.example info@acme.example --domain acme.example --max-credits 2
```

```json 200 theme={null}
{
  "request_id": "req_8a4f2c6d-1b3e-4c5a-9d7f-0e2b4a6c8d10",
  "summary": "2 emails checked: 1 valid, 1 catch-all; domain acme.example is live. 2 credits charged.",
  "cost": { "quoted_credits": 2, "charged_credits": 2 },
  "results": [
    {
      "email": "alex.rivera@acme.example",
      "verdict": "valid",
      "role": false,
      "checked_at": "2026-11-13T09:30:00.000Z"
    },
    {
      "email": "info@acme.example",
      "verdict": "catch-all",
      "reason": "server_accepts_every_address",
      "role": true,
      "checked_at": "2026-11-13T09:30:01.000Z"
    }
  ],
  "domain": { "domain": "acme.example", "status": "live" }
}
```

> [!NOTE]
>
> The example shows the shape of a reply. Addresses on documentation domains (`example.com`, and domains ending in `.example`, `.test`, `.invalid`, `.localhost` or `.local`) are returned as `rejected` with reason `reserved_domain` and are not charged.

## Request

Send at least one of `email`, `emails` or `domain`.

**email** `string`

One email to check. Up to 320 characters.

**emails** `string[]`

Up to 1000 emails. Each up to 320 characters. Duplicates are checked once.

**domain** `string`

A company domain to check. Up to 253 characters.

**purpose** `string` (default: b2b\_outbound)

Why you are asking. One of `b2b_outbound`, `ad_audience`, `own_customer_enrichment`, `fraud_check`. The call is refused if your workspace has not allowed the purpose.

**max\_credits** `integer`

The most this call may charge. 0 to 100000. Never charged past it.

## Response

**request\_id** `string` *required*

The ID of this call. The same value as the `X-Request-Id` header.

**summary** `string` *required*

One plain sentence: how many emails were checked, the verdict counts, the domain status and the charge.

**cost** `object` *required*

**properties**

**quoted\_credits** `number` *required*

The most the call could have charged.

**charged\_credits** `number` *required*

What it charged. Never more than quoted.

**results** `object[]` *required*

One entry per unique email. Empty when only `domain` was sent.

**properties**

**email** `string` *required*

The address as you sent it. Your own input is not masked.

**verdict** `string` *required*

| Value | Meaning |
| - | - |
| `valid` | The mail server accepted the mailbox. |
| `invalid` | The mail server rejected the mailbox. |
| `catch-all` | The server accepts every address, so this one is not proven. |
| `unknown` | No answer. Never a claim that the address is bad. |
| `rejected` | Refused before any lookup. See `reason`. |

**reason** `string`

Why, when there is a reason. For `rejected`: `email_malformed`, `email_disposable`, `reserved_domain`, `placeholder_email`, `personal_email_not_b2b`, `domain_does_not_resolve`. For `unknown`: `credit_cap` when `max_credits` or your balance was reached, or a short reason the check gave no answer. For `catch-all`: `server_accepts_every_address`.

**role** `boolean` *required*

`true` for a shared mailbox such as `info@` or `sales@`.

**checked\_at** `string` *required*

When the check ran, ISO 8601.

**domain** `object`

Present when `domain` was sent and its check completed.

**properties**

**domain** `string` *required*

The domain, normalized.

**status** `string` *required*

`live`, `dead`, `unknown` or `rejected`.

**reason** `string`

Why, for `unknown` (`dns_timeout`) and `rejected`.

## What it costs

| Result | Credits |
| - | - |
| Email verdict `valid`, `invalid` or `catch-all` | 1 per email |
| Email verdict `unknown` or `rejected` | 0 |
| Domain check | 0 |

* `quoted_credits` is 1 per unique email, or `max_credits` if that is lower.
* When `max_credits` is reached, the remaining emails come back as `unknown` with reason `credit_cap`. They are not charged. Send them again in a new request.
* If your balance covers only part of the list, the part it covers is checked and the rest come back the same way.

See [Credits](https://docs-agentic-id.icustomer.ai/credits.md) for how holds and charges work.

## Errors

| Status | Code | Meaning | Retry |
| - | - | - | - |
| 400 | `request.invalid` | The body does not match the schema, or none of `email`, `emails`, `domain` was sent. | No. Fix the body. |
| 400 | `idempotency.key_invalid` | The `Idempotency-Key` is not 8 to 200 printable characters. | No. Fix the key. |
| 401 | `auth.invalid_key` | No valid credential was sent. | No. |
| 401 | `auth.token_expired` | Your sign-in has expired. | After you refresh the token. |
| 402 | `credits.insufficient` | Emails were sent and no credits are available. Nothing was charged. | After adding credits. |
| 403 | `purpose.not_allowed` | Your workspace has not allowed this `purpose`. | No. |
| 409 | `idempotency.in_progress` | The first request with this key is still running. | Yes, after `Retry-After`, same key. |
| 422 | `idempotency.key_reused` | The key was already used with a different body. | No. Use a new key. |
| 429 | `rate_limited` | Too many requests. | Yes, after `Retry-After`. |
| 502 | `service.error` | A fault on our side. | Yes, with the same `Idempotency-Key`. |
| 503 | `service.unavailable` | Temporarily unavailable. | Yes, after `Retry-After`, same key. |
| 504 | `service.timeout` | The call took too long. It may still have completed. | Yes, with the same `Idempotency-Key`. |

See [Errors](https://docs-agentic-id.icustomer.ai/errors.md) for the full list.

## Behaviour

* **Batch limit.** Up to 1000 emails in `emails`, plus one in `email`. Duplicates are checked and charged once.
* **Refused before any paid check.** Malformed, disposable, placeholder (such as `test@`) and reserved-domain addresses, and addresses on a domain that does not resolve, are `rejected` at no charge.
* **Personal mailboxes.** Under the `b2b_outbound` purpose, an address at a personal mail provider is `rejected` with reason `personal_email_not_b2b`.
* **`unknown` is not `invalid`.** It means the check gave no answer. Do not drop the address on that alone.
* **Emails and domain are two checks.** When both are sent and one does not complete, the reply still carries the other. It adds an `incomplete` array, each entry with `part` (`email` or `domain`) and `reason`, and the summary says so. Nothing is charged for the part that did not complete. Ask for it again in a new request.


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