# SalchiMail API

- **OpenAPI Version:** `3.2.0`
- **API Version:** `1.0.0`
- **Terms of service:** <https://salchimail.com/terms>
- **Contact:** SalchiMail support <https://docs.salchimail.com> <hola@salchimail.com>
- **License:** [SalchiMail API Terms](https://salchimail.com/terms)

Verify email addresses one at a time or in batches. SalchiMail never sends
email: mailbox checks stop at `RCPT TO` and never issue `DATA`.

## Authentication

Send your secret key on every request: `Authorization: Bearer sk_live_…`.
Keys are created in the dashboard (`https://app.salchimail.com`), shown once
and stored only as a hash. Keys are secrets: use them from servers, never
from browsers or mobile apps.

`sk_test_…` keys run in **test mode**: no real verification is performed and
no credits are used. Syntax is still checked; the verdict is chosen by the
local part of the address: `valid@…` → `valid`, `invalid@…` → `invalid`,
`risky@…` → `risky` (`catch_all`), `disposable@…` → `risky`
(`disposable_domain`), anything else → `unknown`. Test batches complete
within seconds. Test objects carry `livemode: false`.

## Modes and credits

| `mode`    | What it checks                                                     | Credit used          | Can return `valid` |
| --------- | ------------------------------------------------------------------ | -------------------- | ------------------ |
| `basic`   | Syntax, domain lists (disposable, free), DNS/MX                    | 1 **basic** credit   | No                 |
| `mailbox` | Everything in `basic` + SMTP `RCPT TO` probe and catch-all control | 1 **mailbox** credit | Yes                |

- `basic` never contacts the mail server, so a deliverable domain yields
  `unknown` (`mailbox_not_checked`) or `risky` (list signal), never `valid`.
- `basic`: every completed verification costs 1 basic credit, except
  `dns_temporary` results and repeats of the same address within 30 days.
- `mailbox`: 1 mailbox credit **only when the verdict is not `unknown`**.
  Repeats of the same address within 24 hours and duplicates inside a batch
  are free.
- The two balances are independent: one never pays for the other.
- `credits_charged` on every result tells you exactly what was charged.
- With no credits left the API answers `402 insufficient_credits`.

## Verdicts

| Verdict   | Meaning                                                                                                                                       |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `valid`   | The mail server accepts the recipient and rejects a random control address on the same server. It does not prove the mailbox is read.         |
| `invalid` | Unsupported syntax, a domain that cannot receive mail, or an unambiguous "no such recipient" rejection.                                       |
| `risky`   | Accept-all server, disposable or legacy domain, forwarding, full or disabled mailbox, or a provider directory rejection without confirmation. |
| `unknown` | Mailbox not checked (`basic`), timeout, greylisting, temporary DNS or SMTP failure, probe quota, ambiguous answer.                            |

Do not treat `unknown` as `invalid`. A result with `retry_at` can be
verified again after that time.

## Rate limits

Limits depend on the plan and are reported by `GET /account`. Every response
carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`
(seconds until the window resets). Over the limit the API answers `429` with
`Retry-After`.

## Idempotency

`POST` operations accept an `Idempotency-Key` header (any unique string up
to 255 characters, a UUID is recommended). Keys are kept 24 hours per
account. A retry with the same key and the same body returns the stored
response with `Idempotent-Replayed: true` and charges nothing. The same key
with a different body returns `409 idempotency_key_reused`; a retry while
the first request is still running returns `409 idempotency_in_progress`.

## Errors

Every error uses one shape: `{"error": {"type", "code", "message", "request_id"}}`.
`type` is the broad class, `code` is stable and machine-readable, `message`
is for humans (localised with `Accept-Language`: `en` default, `es`).
`request_id` equals the `X-Request-Id` response header; quote it to support.

| HTTP | `type`             | `code`                                                                                                                            |
| ---- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| 400  | `invalid_request`  | `invalid_json`, `missing_parameter`, `invalid_parameter`, `batch_empty`, `batch_too_large`, `csv_invalid`, `csv_column_not_found` |
| 401  | `authentication`   | `missing_api_key`, `invalid_api_key`, `revoked_api_key`                                                                           |
| 402  | `payment_required` | `insufficient_credits`                                                                                                            |
| 403  | `permission`       | `mode_not_allowed`, `account_suspended`                                                                                           |
| 404  | `not_found`        | `not_found`                                                                                                                       |
| 409  | `conflict`         | `idempotency_key_reused`, `idempotency_in_progress`, `batch_not_cancelable`                                                       |
| 413  | `invalid_request`  | `payload_too_large`                                                                                                               |
| 415  | `invalid_request`  | `unsupported_media_type`                                                                                                          |
| 429  | `rate_limit`       | `rate_limit_exceeded`, `concurrent_batches_exceeded`                                                                              |
| 500  | `api_error`        | `internal_error`                                                                                                                  |
| 503  | `api_error`        | `engine_unavailable`, `verification_timeout`                                                                                      |

New `code` and `reason_code` values may be added without a version bump:
treat unknown values as their `type` or `verdict`.

## Webhooks

Endpoints are configured in the dashboard. Each delivery is a `POST` with a
JSON event and the header
`SalchiMail-Signature: t=<unix seconds>,v1=<hex>`, where `v1` is
`HMAC-SHA256(endpoint_secret, "<t>.<raw request body>")`. Verify it with a
constant-time comparison against the raw body and reject timestamps older
than 5 minutes. During secret rotation several `v1` values may be present:
accept if any matches. Answer `2xx` within 10 seconds; anything else is
retried with exponential backoff for up to 24 hours (8 attempts). Deliveries
can arrive more than once or out of order: deduplicate by event `id`.

## Data retention

Batch inputs and results are deleted 30 days after the batch finishes.
Single verifications are not stored in readable form.

## Contents

**Operations**

- [POST /verify](#scalar-operation-post-verify)
- [POST /batches](#scalar-operation-post-batches)
- [GET /batches](#scalar-operation-get-batches)
- [GET /batches/{batch_id}](#scalar-operation-get-batchesbatch-id)
- [GET /batches/{batch_id}/results](#scalar-operation-get-batchesbatch-idresults)
- [POST /batches/{batch_id}/cancel](#scalar-operation-post-batchesbatch-idcancel)
- [GET /usage](#scalar-operation-get-usage)
- [GET /account](#scalar-operation-get-account)

**Webhooks**

- [POST batch.completed](#scalar-webhook-post-batchcompleted)
- [POST credits.low](#scalar-webhook-post-creditslow)

**Schemas**

- [Mode](#scalar-schema-mode)
- [Verdict](#scalar-schema-verdict)
- [ReasonCode](#scalar-schema-reasoncode)
- [Check](#scalar-schema-check)
- [Flags](#scalar-schema-flags)
- [MxRecord](#scalar-schema-mxrecord)
- [SmtpEvidence](#scalar-schema-smtpevidence)
- [Verification](#scalar-schema-verification)
- [VerifyRequest](#scalar-schema-verifyrequest)
- [BatchCreateRequest](#scalar-schema-batchcreaterequest)
- [BatchCsvUpload](#scalar-schema-batchcsvupload)
- [BatchStatus](#scalar-schema-batchstatus)
- [Batch](#scalar-schema-batch)
- [BatchList](#scalar-schema-batchlist)
- [BatchResult](#scalar-schema-batchresult)
- [BatchResultList](#scalar-schema-batchresultlist)
- [Usage](#scalar-schema-usage)
- [UsageCounters](#scalar-schema-usagecounters)
- [Account](#scalar-schema-account)
- [Error](#scalar-schema-error)
- [ErrorResponse](#scalar-schema-errorresponse)
- [EventBase](#scalar-schema-eventbase)
- [BatchCompletedEvent](#scalar-schema-batchcompletedevent)
- [CreditsLowEvent](#scalar-schema-creditslowevent)

<a id="scalar-context-global-servers"></a>

## Servers

- **URL:** `https://api.salchimail.com/v1`
  - **Description:** Production

<a id="scalar-context-global-authentication"></a>

## Authentication

- **bearerAuth**: HTTP bearer (`API key`)

  Secret API key: `sk_live_…` (live) or `sk_test_…` (test mode). Send it
  as `Authorization: Bearer <key>`.

## Tags

### Verification

Verify one address synchronously.

### Batches

Verify lists asynchronously from JSON or CSV and download results.

### Usage

Remaining credits and usage for the current period.

### Account

The account, plan and limits behind the API key.

### Webhooks

Signed events SalchiMail sends to your endpoints.

## Operations

<a id="scalar-operation-post-verify"></a>

### Verify one email address

- **Method:** `POST`
- **Path:** `/verify`
- **Operation ID:** `verifyEmail`
- **Tags:** Verification

Runs a verification and returns the result in the same response.
`basic` normally answers in well under a second. `mailbox` talks to the
recipient's mail server and can take up to 30 seconds; if it cannot
finish in time the API answers `503 verification_timeout` and charges
nothing. For more than a few addresses use batches.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  Unique key that makes the request safe to retry for 24 hours.

  **Example:**

  ```json
  "6f1c1c0e-6d1f-4f0e-9f58-0d6b0a1c2e3f"
  ```
- **`Accept-Language`**: `string`, default: `"en"`

  Language of `reason` and error `message`. `en` (default) or `es`.

  **Example:**

  ```json
  "es"
  ```

#### Request body

**Required:** `true`

**Content type:** `application/json`

[VerifyRequest](#scalar-schema-verifyrequest)

**Example: basic**

Without mailbox check (1 basic credit)

```json
{
  "email": "ana@example.com"
}
```

**Example: mailbox**

With SMTP mailbox check (1 mailbox credit)

```json
{
  "email": "ana@example.com",
  "mode": "mailbox"
}
```

#### Responses

##### 200 Verification result.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`

  **Example:**

  ```json
  600
  ```
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`

  **Example:**

  ```json
  598
  ```
- **`RateLimit-Reset`**

  Seconds until the current window resets.

  `integer`

  **Example:**

  ```json
  42
  ```
- **`Idempotent-Replayed`**

  Present and `true` when the response was replayed for a repeated `Idempotency-Key`.

  `boolean`

  **Example:**

  ```json
  true
  ```

**Content type:** `application/json`

[Verification](#scalar-schema-verification)

**Example: basicUnknown**

basic mode, domain can receive mail

```json
{
  "id": "ver_3f9a1c0b7d2e4a5f8b6c9d0e1f2a3b4c",
  "object": "verification",
  "livemode": true,
  "email": "ana@example.com",
  "mode": "basic",
  "verdict": "unknown",
  "reason_code": "mailbox_not_checked",
  "reason": "The domain can receive mail; the mailbox was not checked.",
  "flags": {
    "disposable": false,
    "free": false,
    "catch_all": null
  },
  "checks": [
    {
      "name": "syntax",
      "status": "ok"
    },
    {
      "name": "dns",
      "status": "mx"
    }
  ],
  "mx": [
    {
      "host": "mx1.example.com",
      "preference": 10
    }
  ],
  "smtp": null,
  "cached": false,
  "credits_charged": 1,
  "checked_at": "2026-11-17T09:50:00Z",
  "retry_at": null
}
```

**Example: mailboxValid**

mailbox mode, recipient accepted and control rejected

```json
{
  "id": "ver_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",
  "object": "verification",
  "livemode": true,
  "email": "ana@example.com",
  "mode": "mailbox",
  "verdict": "valid",
  "reason_code": "mailbox_exists",
  "reason": "The mail server accepts this recipient and rejects a random one.",
  "flags": {
    "disposable": false,
    "free": false,
    "catch_all": false
  },
  "checks": [
    {
      "name": "syntax",
      "status": "ok"
    },
    {
      "name": "dns",
      "status": "mx"
    },
    {
      "name": "smtp",
      "status": "accepted"
    },
    {
      "name": "catch_all",
      "status": "missing"
    }
  ],
  "mx": [
    {
      "host": "mx1.example.com",
      "preference": 10
    }
  ],
  "smtp": {
    "mx": "mx1.example.com",
    "code": 250,
    "enhanced_code": null,
    "tls": true
  },
  "cached": false,
  "credits_charged": 1,
  "checked_at": "2026-11-17T09:50:04Z",
  "retry_at": null
}
```

**Example: mailboxDeferred**

mailbox mode, greylisted (not charged)

```json
{
  "id": "ver_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "object": "verification",
  "livemode": true,
  "email": "luis@example.org",
  "mode": "mailbox",
  "verdict": "unknown",
  "reason_code": "smtp_temporary",
  "reason": "The mail server deferred the check; try again after retry_at.",
  "flags": {
    "disposable": false,
    "free": false,
    "catch_all": null
  },
  "checks": [
    {
      "name": "syntax",
      "status": "ok"
    },
    {
      "name": "dns",
      "status": "mx"
    },
    {
      "name": "smtp",
      "status": "temporary"
    }
  ],
  "mx": [
    {
      "host": "mail.example.org",
      "preference": 5
    }
  ],
  "smtp": {
    "mx": "mail.example.org",
    "code": 451,
    "enhanced_code": "4.7.1",
    "tls": true
  },
  "cached": false,
  "credits_charged": 0,
  "checked_at": "2026-11-17T09:51:10Z",
  "retry_at": "2026-11-17T10:06:10Z"
}
```

##### 400 The request is malformed or a parameter is invalid.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: missingParameter**

Required field missing

```json
{
  "error": {
    "type": "invalid_request",
    "code": "missing_parameter",
    "message": "The email field is required.",
    "param": "email",
    "request_id": "req_4b5c6d7e8f9a0b1c"
  }
}
```

**Example: batchTooLarge**

Batch above the plan limit

```json
{
  "error": {
    "type": "invalid_request",
    "code": "batch_too_large",
    "message": "This plan accepts up to 100 addresses per batch.",
    "param": "emails",
    "request_id": "req_4b5c6d7e8f9a0b1d"
  }
}
```

##### 401 The API key is missing, invalid or revoked.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`WWW-Authenticate`**

  Always `Bearer`.

  `string`

  **Example:**

  ```json
  "Bearer"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: invalidKey**

Unknown key

```json
{
  "error": {
    "type": "authentication",
    "code": "invalid_api_key",
    "message": "The API key is not valid.",
    "request_id": "req_4b5c6d7e8f9a0b1e"
  }
}
```

##### 402 Not enough credits of the type the request needs.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: insufficientCredits**

No mailbox credits left

```json
{
  "error": {
    "type": "payment_required",
    "code": "insufficient_credits",
    "message": "This request needs 3 mailbox credits and the account has 0.",
    "request_id": "req_4b5c6d7e8f9a0b1f"
  }
}
```

##### 403 The key is valid but the account may not do this.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: modeNotAllowed**

Mode not available to this account

```json
{
  "error": {
    "type": "permission",
    "code": "mode_not_allowed",
    "message": "Mailbox verification is not enabled for this account.",
    "param": "mode",
    "request_id": "req_4b5c6d7e8f9a0b20"
  }
}
```

##### 409 Idempotency conflict or the resource is in a state that does not allow the operation.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: keyReused**

Same key, different body

```json
{
  "error": {
    "type": "conflict",
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request.",
    "request_id": "req_4b5c6d7e8f9a0b22"
  }
}
```

**Example: notCancelable**

Batch already finished

```json
{
  "error": {
    "type": "conflict",
    "code": "batch_not_cancelable",
    "message": "A completed batch cannot be canceled.",
    "request_id": "req_4b5c6d7e8f9a0b23"
  }
}
```

##### 415 Use `application/json` or, for CSV batches, `multipart/form-data`.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: unsupported**

Wrong Content-Type

```json
{
  "error": {
    "type": "invalid_request",
    "code": "unsupported_media_type",
    "message": "Use Content-Type application/json.",
    "request_id": "req_4b5c6d7e8f9a0b25"
  }
}
```

##### 429 Rate limit or concurrent batch limit exceeded.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

  **Example:**

  ```json
  12
  ```
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`

  **Example:**

  ```json
  600
  ```
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`

  **Example:**

  ```json
  598
  ```
- **`RateLimit-Reset`**

  Seconds until the current window resets.

  `integer`

  **Example:**

  ```json
  42
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: rateLimited**

Too many requests

```json
{
  "error": {
    "type": "rate_limit",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry in 12 seconds.",
    "request_id": "req_4b5c6d7e8f9a0b26"
  }
}
```

##### 500 Unexpected error on our side. Safe to retry with the same `Idempotency-Key`.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: internal**

Internal error

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "req_4b5c6d7e8f9a0b27"
  }
}
```

##### 503 The verification engine is unavailable or the check timed out. Nothing was charged.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

  **Example:**

  ```json
  12
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: timeout**

Mailbox check did not finish in time

```json
{
  "error": {
    "type": "api_error",
    "code": "verification_timeout",
    "message": "The verification did not finish in time. Nothing was charged.",
    "request_id": "req_4b5c6d7e8f9a0b28"
  }
}
```

<a id="scalar-operation-post-batches"></a>

### Create a batch from JSON or CSV

- **Method:** `POST`
- **Path:** `/batches`
- **Operation ID:** `createBatch`
- **Tags:** Batches

Queues a list for asynchronous verification and returns `202` at once.

- **JSON**: up to 10,000 addresses in `emails`.
- **CSV**: `multipart/form-data` with a UTF-8 file of up to 10 MB and
  100,000 data rows. A header row is required and `email_column` must
  match one column name exactly. Only that column is stored; other
  columns are discarded. Join results back by `row`.

Your plan may set a lower limit (`limits.max_batch_size` in
`GET /account`). Credits for every unique address are reserved when the
batch is created (`402` if the balance is too low) and unused credits
are returned when it finishes. Duplicated addresses are verified once
and charged once.

`mailbox` batches respect per-domain and per-server probe quotas and
retry deferred addresses, so large lists concentrated on a few domains
can take hours or days. Addresses still unresolved at `deadline_at`
end as `unknown` and are not charged.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  Unique key that makes the request safe to retry for 24 hours.

  **Example:**

  ```json
  "6f1c1c0e-6d1f-4f0e-9f58-0d6b0a1c2e3f"
  ```

#### Request body

**Required:** `true`

**Content type:** `application/json`

[BatchCreateRequest](#scalar-schema-batchcreaterequest)

**Example: json**

JSON list with mailbox check

```json
{
  "emails": [
    "ana@example.com",
    "luis@example.org",
    "not-an-email"
  ],
  "mode": "mailbox",
  "name": "November newsletter"
}
```

**Content type:** `multipart/form-data`

[BatchCsvUpload](#scalar-schema-batchcsvupload)

**Example: csv**

CSV upload (fields of the multipart form)

```json
{
  "file": "id,email\n1,ana@example.com\n2,luis@example.org\n",
  "mode": "mailbox",
  "email_column": "email",
  "delimiter": "comma",
  "name": "November newsletter"
}
```

**Encoding:**

- **`file`**
  - Content-Type: `text/csv`

#### Responses

##### 202 Batch accepted and queued.

**Headers:**

- **`Location`**

  URL of the new batch.

  `string`, format: `uri`

  **Example:**

  ```json
  "https://api.salchimail.com/v1/batches/bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"
  ```
- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`

  **Example:**

  ```json
  600
  ```
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`

  **Example:**

  ```json
  598
  ```
- **`RateLimit-Reset`**

  Seconds until the current window resets.

  `integer`

  **Example:**

  ```json
  42
  ```
- **`Idempotent-Replayed`**

  Present and `true` when the response was replayed for a repeated `Idempotency-Key`.

  `boolean`

  **Example:**

  ```json
  true
  ```

**Content type:** `application/json`

[Batch](#scalar-schema-batch)

**Example: queued**

Batch just created

```json
{
  "id": "bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
  "object": "batch",
  "livemode": true,
  "name": "November newsletter",
  "source": "json",
  "mode": "mailbox",
  "status": "queued",
  "total": 3,
  "unique": 3,
  "processed": 0,
  "summary": {
    "valid": 0,
    "invalid": 0,
    "risky": 0,
    "unknown": 0
  },
  "credits": {
    "type": "mailbox",
    "reserved": 3,
    "charged": 0
  },
  "created_at": "2026-11-17T09:50:00Z",
  "started_at": null,
  "finished_at": null,
  "deadline_at": null,
  "results_expire_at": null
}
```

##### 400 The request is malformed or a parameter is invalid.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: missingParameter**

Required field missing

```json
{
  "error": {
    "type": "invalid_request",
    "code": "missing_parameter",
    "message": "The email field is required.",
    "param": "email",
    "request_id": "req_4b5c6d7e8f9a0b1c"
  }
}
```

**Example: batchTooLarge**

Batch above the plan limit

```json
{
  "error": {
    "type": "invalid_request",
    "code": "batch_too_large",
    "message": "This plan accepts up to 100 addresses per batch.",
    "param": "emails",
    "request_id": "req_4b5c6d7e8f9a0b1d"
  }
}
```

##### 401 The API key is missing, invalid or revoked.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`WWW-Authenticate`**

  Always `Bearer`.

  `string`

  **Example:**

  ```json
  "Bearer"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: invalidKey**

Unknown key

```json
{
  "error": {
    "type": "authentication",
    "code": "invalid_api_key",
    "message": "The API key is not valid.",
    "request_id": "req_4b5c6d7e8f9a0b1e"
  }
}
```

##### 402 Not enough credits of the type the request needs.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: insufficientCredits**

No mailbox credits left

```json
{
  "error": {
    "type": "payment_required",
    "code": "insufficient_credits",
    "message": "This request needs 3 mailbox credits and the account has 0.",
    "request_id": "req_4b5c6d7e8f9a0b1f"
  }
}
```

##### 403 The key is valid but the account may not do this.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: modeNotAllowed**

Mode not available to this account

```json
{
  "error": {
    "type": "permission",
    "code": "mode_not_allowed",
    "message": "Mailbox verification is not enabled for this account.",
    "param": "mode",
    "request_id": "req_4b5c6d7e8f9a0b20"
  }
}
```

##### 409 Idempotency conflict or the resource is in a state that does not allow the operation.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: keyReused**

Same key, different body

```json
{
  "error": {
    "type": "conflict",
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request.",
    "request_id": "req_4b5c6d7e8f9a0b22"
  }
}
```

**Example: notCancelable**

Batch already finished

```json
{
  "error": {
    "type": "conflict",
    "code": "batch_not_cancelable",
    "message": "A completed batch cannot be canceled.",
    "request_id": "req_4b5c6d7e8f9a0b23"
  }
}
```

##### 413 The body exceeds 2 MB (JSON) or 10 MB (CSV).

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: tooLarge**

CSV over 10 MB

```json
{
  "error": {
    "type": "invalid_request",
    "code": "payload_too_large",
    "message": "The file exceeds 10 MB. Split it into several batches.",
    "request_id": "req_4b5c6d7e8f9a0b24"
  }
}
```

##### 415 Use `application/json` or, for CSV batches, `multipart/form-data`.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: unsupported**

Wrong Content-Type

```json
{
  "error": {
    "type": "invalid_request",
    "code": "unsupported_media_type",
    "message": "Use Content-Type application/json.",
    "request_id": "req_4b5c6d7e8f9a0b25"
  }
}
```

##### 429 Rate limit or concurrent batch limit exceeded.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

  **Example:**

  ```json
  12
  ```
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`

  **Example:**

  ```json
  600
  ```
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`

  **Example:**

  ```json
  598
  ```
- **`RateLimit-Reset`**

  Seconds until the current window resets.

  `integer`

  **Example:**

  ```json
  42
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: rateLimited**

Too many requests

```json
{
  "error": {
    "type": "rate_limit",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry in 12 seconds.",
    "request_id": "req_4b5c6d7e8f9a0b26"
  }
}
```

##### 500 Unexpected error on our side. Safe to retry with the same `Idempotency-Key`.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: internal**

Internal error

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "req_4b5c6d7e8f9a0b27"
  }
}
```

##### 503 The verification engine is unavailable or the check timed out. Nothing was charged.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

  **Example:**

  ```json
  12
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: timeout**

Mailbox check did not finish in time

```json
{
  "error": {
    "type": "api_error",
    "code": "verification_timeout",
    "message": "The verification did not finish in time. Nothing was charged.",
    "request_id": "req_4b5c6d7e8f9a0b28"
  }
}
```

<a id="scalar-operation-get-batches"></a>

### List batches

- **Method:** `GET`
- **Path:** `/batches`
- **Operation ID:** `listBatches`
- **Tags:** Batches

Returns the account's batches, newest first.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Query parameters

- **`limit`**: `integer`, default: `20`, minimum: `1`, maximum: `100`

  Page size.

  **Example:**

  ```json
  20
  ```
- **`cursor`**: `string`, maxLength: `255`

  Opaque `next_cursor` from the previous page.

  **Example:**

  ```json
  "eyJyb3ciOjN9"
  ```

#### Responses

##### 200 A page of batches.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`

  **Example:**

  ```json
  600
  ```
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`

  **Example:**

  ```json
  598
  ```
- **`RateLimit-Reset`**

  Seconds until the current window resets.

  `integer`

  **Example:**

  ```json
  42
  ```

**Content type:** `application/json`

[BatchList](#scalar-schema-batchlist)

**Example: page**

One completed batch

```json
{
  "object": "list",
  "data": [
    {
      "id": "bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
      "object": "batch",
      "livemode": true,
      "name": "November newsletter",
      "source": "json",
      "mode": "mailbox",
      "status": "completed",
      "total": 3,
      "unique": 3,
      "processed": 3,
      "summary": {
        "valid": 1,
        "invalid": 1,
        "risky": 0,
        "unknown": 1
      },
      "credits": {
        "type": "mailbox",
        "reserved": 0,
        "charged": 2
      },
      "created_at": "2026-11-17T09:50:00Z",
      "started_at": "2026-11-17T09:50:02Z",
      "finished_at": "2026-11-17T10:21:40Z",
      "deadline_at": "2026-11-23T09:50:02Z",
      "results_expire_at": "2026-12-17T10:21:40Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

##### 400 The request is malformed or a parameter is invalid.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: missingParameter**

Required field missing

```json
{
  "error": {
    "type": "invalid_request",
    "code": "missing_parameter",
    "message": "The email field is required.",
    "param": "email",
    "request_id": "req_4b5c6d7e8f9a0b1c"
  }
}
```

**Example: batchTooLarge**

Batch above the plan limit

```json
{
  "error": {
    "type": "invalid_request",
    "code": "batch_too_large",
    "message": "This plan accepts up to 100 addresses per batch.",
    "param": "emails",
    "request_id": "req_4b5c6d7e8f9a0b1d"
  }
}
```

##### 401 The API key is missing, invalid or revoked.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`WWW-Authenticate`**

  Always `Bearer`.

  `string`

  **Example:**

  ```json
  "Bearer"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: invalidKey**

Unknown key

```json
{
  "error": {
    "type": "authentication",
    "code": "invalid_api_key",
    "message": "The API key is not valid.",
    "request_id": "req_4b5c6d7e8f9a0b1e"
  }
}
```

##### 429 Rate limit or concurrent batch limit exceeded.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

  **Example:**

  ```json
  12
  ```
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`

  **Example:**

  ```json
  600
  ```
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`

  **Example:**

  ```json
  598
  ```
- **`RateLimit-Reset`**

  Seconds until the current window resets.

  `integer`

  **Example:**

  ```json
  42
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: rateLimited**

Too many requests

```json
{
  "error": {
    "type": "rate_limit",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry in 12 seconds.",
    "request_id": "req_4b5c6d7e8f9a0b26"
  }
}
```

##### 500 Unexpected error on our side. Safe to retry with the same `Idempotency-Key`.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: internal**

Internal error

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "req_4b5c6d7e8f9a0b27"
  }
}
```

<a id="scalar-operation-get-batchesbatch-id"></a>

### Get batch status

- **Method:** `GET`
- **Path:** `/batches/{batch_id}`
- **Operation ID:** `getBatch`
- **Tags:** Batches

Poll this endpoint (every few seconds at most) or subscribe to the
`batch.completed` webhook. `processed` grows as addresses reach a final
result.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Path parameters

- **`batch_id` (required)**: `string`, pattern: `^bat_[a-f0-9]{32}$`

  Batch identifier.

  **Example:**

  ```json
  "bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"
  ```

#### Responses

##### 200 The batch.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`

  **Example:**

  ```json
  600
  ```
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`

  **Example:**

  ```json
  598
  ```
- **`RateLimit-Reset`**

  Seconds until the current window resets.

  `integer`

  **Example:**

  ```json
  42
  ```

**Content type:** `application/json`

[Batch](#scalar-schema-batch)

**Example: processing**

Batch in progress

```json
{
  "id": "bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
  "object": "batch",
  "livemode": true,
  "name": "November newsletter",
  "source": "json",
  "mode": "mailbox",
  "status": "processing",
  "total": 3,
  "unique": 3,
  "processed": 2,
  "summary": {
    "valid": 1,
    "invalid": 1,
    "risky": 0,
    "unknown": 0
  },
  "credits": {
    "type": "mailbox",
    "reserved": 1,
    "charged": 2
  },
  "created_at": "2026-11-17T09:50:00Z",
  "started_at": "2026-11-17T09:50:02Z",
  "finished_at": null,
  "deadline_at": "2026-11-23T09:50:02Z",
  "results_expire_at": null
}
```

##### 401 The API key is missing, invalid or revoked.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`WWW-Authenticate`**

  Always `Bearer`.

  `string`

  **Example:**

  ```json
  "Bearer"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: invalidKey**

Unknown key

```json
{
  "error": {
    "type": "authentication",
    "code": "invalid_api_key",
    "message": "The API key is not valid.",
    "request_id": "req_4b5c6d7e8f9a0b1e"
  }
}
```

##### 404 The resource does not exist, belongs to another account or has expired.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: notFound**

Unknown batch

```json
{
  "error": {
    "type": "not_found",
    "code": "not_found",
    "message": "Batch not found.",
    "request_id": "req_4b5c6d7e8f9a0b21"
  }
}
```

##### 429 Rate limit or concurrent batch limit exceeded.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

  **Example:**

  ```json
  12
  ```
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`

  **Example:**

  ```json
  600
  ```
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`

  **Example:**

  ```json
  598
  ```
- **`RateLimit-Reset`**

  Seconds until the current window resets.

  `integer`

  **Example:**

  ```json
  42
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: rateLimited**

Too many requests

```json
{
  "error": {
    "type": "rate_limit",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry in 12 seconds.",
    "request_id": "req_4b5c6d7e8f9a0b26"
  }
}
```

##### 500 Unexpected error on our side. Safe to retry with the same `Idempotency-Key`.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: internal**

Internal error

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "req_4b5c6d7e8f9a0b27"
  }
}
```

<a id="scalar-operation-get-batchesbatch-idresults"></a>

### Get batch results (JSON or CSV)

- **Method:** `GET`
- **Path:** `/batches/{batch_id}/results`
- **Operation ID:** `listBatchResults`
- **Tags:** Batches

Returns results ordered by `row`. Only rows with a final result are
listed, so pages requested while the batch is `processing` are partial:
wait for a terminal status for a complete export. Rows never processed
in a `canceled` batch are omitted.

With `format=csv` the body is CSV with the header
`row,input,email,verdict,reason_code,disposable,free,catch_all,credits_charged,checked_at`
and the next page is given by the `Link` header (`rel="next"`).
Results are deleted at `results_expire_at`; after that this endpoint
answers `404`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Path parameters

- **`batch_id` (required)**: `string`, pattern: `^bat_[a-f0-9]{32}$`

  Batch identifier.

  **Example:**

  ```json
  "bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"
  ```

#### Query parameters

- **`format`**: `string`, possible values: `"json", "csv"`, default: `"json"`

  Response format.

  **Example:**

  ```json
  "json"
  ```
- **`verdict`**: `string`, possible values: `"valid", "invalid", "risky", "unknown"`

  Only return rows with this verdict.

  **Example:**

  ```json
  "valid"
  ```
- **`limit`**: `integer`, default: `100`, minimum: `1`, maximum: `10000`

  Page size. Maximum 1,000 for JSON and 10,000 for CSV.

  **Example:**

  ```json
  100
  ```
- **`cursor`**: `string`, maxLength: `255`

  Opaque `next_cursor` from the previous page.

  **Example:**

  ```json
  "eyJyb3ciOjN9"
  ```

#### Header parameters

- **`Accept-Language`**: `string`, default: `"en"`

  Language of `reason` and error `message`. `en` (default) or `es`.

  **Example:**

  ```json
  "es"
  ```

#### Responses

##### 200 A page of results.

**Headers:**

- **`Link`**

  Next page as `<url>; rel="next"`. Absent on the last page.

  `string`

  **Example:**

  ```json
  "<https://api.salchimail.com/v1/batches/bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b/results?format=csv&cursor=eyJyb3ciOjN9>; rel=\"next\""
  ```
- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`

  **Example:**

  ```json
  600
  ```
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`

  **Example:**

  ```json
  598
  ```
- **`RateLimit-Reset`**

  Seconds until the current window resets.

  `integer`

  **Example:**

  ```json
  42
  ```

**Content type:** `application/json`

[BatchResultList](#scalar-schema-batchresultlist)

**Example: page**

Two rows, more available

```json
{
  "object": "list",
  "data": [
    {
      "row": 1,
      "input": "Ana@Example.com",
      "duplicate": false,
      "id": "ver_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",
      "object": "verification",
      "livemode": true,
      "email": "ana@example.com",
      "mode": "mailbox",
      "verdict": "valid",
      "reason_code": "mailbox_exists",
      "reason": "The mail server accepts this recipient and rejects a random one.",
      "flags": {
        "disposable": false,
        "free": false,
        "catch_all": false
      },
      "checks": [
        {
          "name": "syntax",
          "status": "ok"
        },
        {
          "name": "dns",
          "status": "mx"
        },
        {
          "name": "smtp",
          "status": "accepted"
        },
        {
          "name": "catch_all",
          "status": "missing"
        }
      ],
      "mx": [
        {
          "host": "mx1.example.com",
          "preference": 10
        }
      ],
      "smtp": {
        "mx": "mx1.example.com",
        "code": 250,
        "enhanced_code": null,
        "tls": true
      },
      "cached": false,
      "credits_charged": 1,
      "checked_at": "2026-11-17T09:50:04Z",
      "retry_at": null
    },
    {
      "row": 3,
      "input": "not-an-email",
      "duplicate": false,
      "id": "ver_1b2c3d4e5f60718293a4b5c6d7e8f9a0",
      "object": "verification",
      "livemode": true,
      "email": "not-an-email",
      "mode": "mailbox",
      "verdict": "invalid",
      "reason_code": "syntax_invalid",
      "reason": "The address is not a valid email.",
      "flags": {
        "disposable": false,
        "free": false,
        "catch_all": null
      },
      "checks": [
        {
          "name": "syntax",
          "status": "invalid"
        }
      ],
      "mx": [],
      "smtp": null,
      "cached": false,
      "credits_charged": 1,
      "checked_at": "2026-11-17T09:50:02Z",
      "retry_at": null
    }
  ],
  "has_more": true,
  "next_cursor": "eyJyb3ciOjN9"
}
```

**Content type:** `text/csv`

`string`

**Example: page**

Same page as CSV

```json
"row,input,email,verdict,reason_code,disposable,free,catch_all,credits_charged,checked_at\n1,Ana@Example.com,ana@example.com,valid,mailbox_exists,false,false,false,1,2026-11-17T09:50:04Z\n3,not-an-email,not-an-email,invalid,syntax_invalid,false,false,,1,2026-11-17T09:50:02Z\n"
```

##### 400 The request is malformed or a parameter is invalid.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: missingParameter**

Required field missing

```json
{
  "error": {
    "type": "invalid_request",
    "code": "missing_parameter",
    "message": "The email field is required.",
    "param": "email",
    "request_id": "req_4b5c6d7e8f9a0b1c"
  }
}
```

**Example: batchTooLarge**

Batch above the plan limit

```json
{
  "error": {
    "type": "invalid_request",
    "code": "batch_too_large",
    "message": "This plan accepts up to 100 addresses per batch.",
    "param": "emails",
    "request_id": "req_4b5c6d7e8f9a0b1d"
  }
}
```

##### 401 The API key is missing, invalid or revoked.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`WWW-Authenticate`**

  Always `Bearer`.

  `string`

  **Example:**

  ```json
  "Bearer"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: invalidKey**

Unknown key

```json
{
  "error": {
    "type": "authentication",
    "code": "invalid_api_key",
    "message": "The API key is not valid.",
    "request_id": "req_4b5c6d7e8f9a0b1e"
  }
}
```

##### 404 The resource does not exist, belongs to another account or has expired.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: notFound**

Unknown batch

```json
{
  "error": {
    "type": "not_found",
    "code": "not_found",
    "message": "Batch not found.",
    "request_id": "req_4b5c6d7e8f9a0b21"
  }
}
```

##### 429 Rate limit or concurrent batch limit exceeded.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

  **Example:**

  ```json
  12
  ```
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`

  **Example:**

  ```json
  600
  ```
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`

  **Example:**

  ```json
  598
  ```
- **`RateLimit-Reset`**

  Seconds until the current window resets.

  `integer`

  **Example:**

  ```json
  42
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: rateLimited**

Too many requests

```json
{
  "error": {
    "type": "rate_limit",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry in 12 seconds.",
    "request_id": "req_4b5c6d7e8f9a0b26"
  }
}
```

##### 500 Unexpected error on our side. Safe to retry with the same `Idempotency-Key`.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: internal**

Internal error

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "req_4b5c6d7e8f9a0b27"
  }
}
```

<a id="scalar-operation-post-batchesbatch-idcancel"></a>

### Cancel a batch

- **Method:** `POST`
- **Path:** `/batches/{batch_id}/cancel`
- **Operation ID:** `cancelBatch`
- **Tags:** Batches

Stops a `queued` or `processing` batch. Results already produced stay
available and charged; credits reserved for the rest are returned.
Canceling a batch that is already `canceled` returns it unchanged; a
`completed` or `failed` batch answers `409 batch_not_cancelable`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Path parameters

- **`batch_id` (required)**: `string`, pattern: `^bat_[a-f0-9]{32}$`

  Batch identifier.

  **Example:**

  ```json
  "bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"
  ```

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  Unique key that makes the request safe to retry for 24 hours.

  **Example:**

  ```json
  "6f1c1c0e-6d1f-4f0e-9f58-0d6b0a1c2e3f"
  ```

#### Responses

##### 200 The canceled batch.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`

  **Example:**

  ```json
  600
  ```
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`

  **Example:**

  ```json
  598
  ```
- **`RateLimit-Reset`**

  Seconds until the current window resets.

  `integer`

  **Example:**

  ```json
  42
  ```
- **`Idempotent-Replayed`**

  Present and `true` when the response was replayed for a repeated `Idempotency-Key`.

  `boolean`

  **Example:**

  ```json
  true
  ```

**Content type:** `application/json`

[Batch](#scalar-schema-batch)

**Example: canceled**

Canceled after two results

```json
{
  "id": "bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
  "object": "batch",
  "livemode": true,
  "name": "November newsletter",
  "source": "json",
  "mode": "mailbox",
  "status": "canceled",
  "total": 3,
  "unique": 3,
  "processed": 2,
  "summary": {
    "valid": 1,
    "invalid": 1,
    "risky": 0,
    "unknown": 0
  },
  "credits": {
    "type": "mailbox",
    "reserved": 0,
    "charged": 2
  },
  "created_at": "2026-11-17T09:50:00Z",
  "started_at": "2026-11-17T09:50:02Z",
  "finished_at": "2026-11-17T09:55:00Z",
  "deadline_at": "2026-11-23T09:50:02Z",
  "results_expire_at": "2026-12-17T09:55:00Z"
}
```

##### 401 The API key is missing, invalid or revoked.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`WWW-Authenticate`**

  Always `Bearer`.

  `string`

  **Example:**

  ```json
  "Bearer"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: invalidKey**

Unknown key

```json
{
  "error": {
    "type": "authentication",
    "code": "invalid_api_key",
    "message": "The API key is not valid.",
    "request_id": "req_4b5c6d7e8f9a0b1e"
  }
}
```

##### 404 The resource does not exist, belongs to another account or has expired.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: notFound**

Unknown batch

```json
{
  "error": {
    "type": "not_found",
    "code": "not_found",
    "message": "Batch not found.",
    "request_id": "req_4b5c6d7e8f9a0b21"
  }
}
```

##### 409 Idempotency conflict or the resource is in a state that does not allow the operation.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: keyReused**

Same key, different body

```json
{
  "error": {
    "type": "conflict",
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request.",
    "request_id": "req_4b5c6d7e8f9a0b22"
  }
}
```

**Example: notCancelable**

Batch already finished

```json
{
  "error": {
    "type": "conflict",
    "code": "batch_not_cancelable",
    "message": "A completed batch cannot be canceled.",
    "request_id": "req_4b5c6d7e8f9a0b23"
  }
}
```

##### 429 Rate limit or concurrent batch limit exceeded.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

  **Example:**

  ```json
  12
  ```
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`

  **Example:**

  ```json
  600
  ```
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`

  **Example:**

  ```json
  598
  ```
- **`RateLimit-Reset`**

  Seconds until the current window resets.

  `integer`

  **Example:**

  ```json
  42
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: rateLimited**

Too many requests

```json
{
  "error": {
    "type": "rate_limit",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry in 12 seconds.",
    "request_id": "req_4b5c6d7e8f9a0b26"
  }
}
```

##### 500 Unexpected error on our side. Safe to retry with the same `Idempotency-Key`.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: internal**

Internal error

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "req_4b5c6d7e8f9a0b27"
  }
}
```

<a id="scalar-operation-get-usage"></a>

### Get remaining credits and current usage

- **Method:** `GET`
- **Path:** `/usage`
- **Operation ID:** `getUsage`
- **Tags:** Usage

`remaining` is what you can spend now; credits held by running batches
are reported separately in `reserved`. Basic credits are a monthly
allowance that resets at `resets_at` and does not roll over. Mailbox
credits come from one-off packs; credits closest to expiring are spent
first.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Responses

##### 200 Credits and usage.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`

  **Example:**

  ```json
  600
  ```
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`

  **Example:**

  ```json
  598
  ```
- **`RateLimit-Reset`**

  Seconds until the current window resets.

  `integer`

  **Example:**

  ```json
  42
  ```

**Content type:** `application/json`

[Usage](#scalar-schema-usage)

**Example: usage**

Basic plan with a mailbox pack

```json
{
  "object": "usage",
  "livemode": true,
  "credits": {
    "basic": {
      "remaining": 18760,
      "reserved": 0,
      "granted": 20000,
      "resets_at": "2026-12-01T00:00:00Z"
    },
    "mailbox": {
      "remaining": 2311,
      "reserved": 1,
      "next_expiry": null
    }
  },
  "period": {
    "start": "2026-11-01T00:00:00Z",
    "end": "2026-12-01T00:00:00Z"
  },
  "usage": {
    "basic": {
      "verifications": 1302,
      "credits_charged": 1240
    },
    "mailbox": {
      "verifications": 214,
      "credits_charged": 188
    }
  }
}
```

##### 401 The API key is missing, invalid or revoked.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`WWW-Authenticate`**

  Always `Bearer`.

  `string`

  **Example:**

  ```json
  "Bearer"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: invalidKey**

Unknown key

```json
{
  "error": {
    "type": "authentication",
    "code": "invalid_api_key",
    "message": "The API key is not valid.",
    "request_id": "req_4b5c6d7e8f9a0b1e"
  }
}
```

##### 429 Rate limit or concurrent batch limit exceeded.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

  **Example:**

  ```json
  12
  ```
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`

  **Example:**

  ```json
  600
  ```
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`

  **Example:**

  ```json
  598
  ```
- **`RateLimit-Reset`**

  Seconds until the current window resets.

  `integer`

  **Example:**

  ```json
  42
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: rateLimited**

Too many requests

```json
{
  "error": {
    "type": "rate_limit",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry in 12 seconds.",
    "request_id": "req_4b5c6d7e8f9a0b26"
  }
}
```

##### 500 Unexpected error on our side. Safe to retry with the same `Idempotency-Key`.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: internal**

Internal error

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "req_4b5c6d7e8f9a0b27"
  }
}
```

<a id="scalar-operation-get-account"></a>

### Get the account behind the API key

- **Method:** `GET`
- **Path:** `/account`
- **Operation ID:** `getAccount`
- **Tags:** Account

Returns the organisation, its plan, the key in use and the limits that apply to it.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Responses

##### 200 The account.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`

  **Example:**

  ```json
  600
  ```
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`

  **Example:**

  ```json
  598
  ```
- **`RateLimit-Reset`**

  Seconds until the current window resets.

  `integer`

  **Example:**

  ```json
  42
  ```

**Content type:** `application/json`

[Account](#scalar-schema-account)

**Example: account**

Organisation on the Basic plan

```json
{
  "id": "org_7a8b9c0d1e2f3a4b",
  "object": "account",
  "livemode": true,
  "name": "Acme Marketing",
  "plan": {
    "id": "basic",
    "status": "active"
  },
  "api_key": {
    "id": "key_2f3a4b5c6d7e8f9a",
    "name": "Production server",
    "prefix": "sk_live_a1b2",
    "created_at": "2026-11-02T08:15:00Z"
  },
  "limits": {
    "requests_per_minute": 600,
    "max_batch_size": 100000,
    "max_concurrent_batches": 3,
    "modes": [
      "basic",
      "mailbox"
    ]
  },
  "created_at": "2026-11-02T08:10:00Z"
}
```

##### 401 The API key is missing, invalid or revoked.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`WWW-Authenticate`**

  Always `Bearer`.

  `string`

  **Example:**

  ```json
  "Bearer"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: invalidKey**

Unknown key

```json
{
  "error": {
    "type": "authentication",
    "code": "invalid_api_key",
    "message": "The API key is not valid.",
    "request_id": "req_4b5c6d7e8f9a0b1e"
  }
}
```

##### 429 Rate limit or concurrent batch limit exceeded.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

  **Example:**

  ```json
  12
  ```
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`

  **Example:**

  ```json
  600
  ```
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`

  **Example:**

  ```json
  598
  ```
- **`RateLimit-Reset`**

  Seconds until the current window resets.

  `integer`

  **Example:**

  ```json
  42
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: rateLimited**

Too many requests

```json
{
  "error": {
    "type": "rate_limit",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry in 12 seconds.",
    "request_id": "req_4b5c6d7e8f9a0b26"
  }
}
```

##### 500 Unexpected error on our side. Safe to retry with the same `Idempotency-Key`.

**Headers:**

- **`X-Request-Id`**

  Identifier of this request; the same value as `error.request_id`.

  `string`

  **Example:**

  ```json
  "req_4b5c6d7e8f9a0b1c"
  ```

**Content type:** `application/json`

[ErrorResponse](#scalar-schema-errorresponse)

**Example: internal**

Internal error

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "req_4b5c6d7e8f9a0b27"
  }
}
```

## Webhooks

<a id="scalar-webhook-post-batchcompleted"></a>

### A batch finished

- **Method:** `POST`
- **Webhook:** `batch.completed`
- **Operation ID:** `onBatchCompleted`
- **Tags:** Webhooks

Sent when a batch reaches `completed` or `failed` (check
`data.batch.status`). Not sent for batches you cancel. Fetch the rows
with `GET /batches/{batch_id}/results`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

No authentication required.

#### Header parameters

- **`SalchiMail-Signature` (required)**: `string`

  `t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with the
  endpoint secret>`.

  **Example:**

  ```json
  "t=1794909701,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd"
  ```

#### Request body

**Required:** `true`

**Content type:** `application/json`

[BatchCompletedEvent](#scalar-schema-batchcompletedevent)

**Example: completed**

Batch completed

```json
{
  "id": "evt_9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f",
  "object": "event",
  "type": "batch.completed",
  "livemode": true,
  "created_at": "2026-11-17T10:21:41Z",
  "data": {
    "batch": {
      "id": "bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
      "object": "batch",
      "livemode": true,
      "name": "November newsletter",
      "source": "json",
      "mode": "mailbox",
      "status": "completed",
      "total": 3,
      "unique": 3,
      "processed": 3,
      "summary": {
        "valid": 1,
        "invalid": 1,
        "risky": 0,
        "unknown": 1
      },
      "credits": {
        "type": "mailbox",
        "reserved": 0,
        "charged": 2
      },
      "created_at": "2026-11-17T09:50:00Z",
      "started_at": "2026-11-17T09:50:02Z",
      "finished_at": "2026-11-17T10:21:40Z",
      "deadline_at": "2026-11-23T09:50:02Z",
      "results_expire_at": "2026-12-17T10:21:40Z"
    }
  }
}
```

#### Responses

##### 200 Acknowledged. Any `2xx` within 10 seconds stops retries.

##### 4XX Any non-2xx answer or a timeout schedules a retry.

<a id="scalar-webhook-post-creditslow"></a>

### A credit balance fell below its threshold

- **Method:** `POST`
- **Webhook:** `credits.low`
- **Operation ID:** `onCreditsLow`
- **Tags:** Webhooks

Sent once each time a balance crosses the threshold configured in the
dashboard (default: 10% of the last grant). It is sent again only after
the balance has been topped up above the threshold and falls below it
again.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

No authentication required.

#### Header parameters

- **`SalchiMail-Signature` (required)**: `string`

  `t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with the
  endpoint secret>`.

  **Example:**

  ```json
  "t=1794909701,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd"
  ```

#### Request body

**Required:** `true`

**Content type:** `application/json`

[CreditsLowEvent](#scalar-schema-creditslowevent)

**Example: low**

Mailbox credits running low

```json
{
  "id": "evt_0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a",
  "object": "event",
  "type": "credits.low",
  "livemode": true,
  "created_at": "2026-11-17T11:02:13Z",
  "data": {
    "credit_type": "mailbox",
    "remaining": 249,
    "threshold": 250
  }
}
```

#### Responses

##### 200 Acknowledged. Any `2xx` within 10 seconds stops retries.

##### 4XX Any non-2xx answer or a timeout schedules a retry.

## Schemas

<a id="scalar-schema-mode"></a>

### Mode

**Type:** `string`, possible values: `"basic", "mailbox"`

`basic`: syntax, domain lists and DNS (1 basic credit). `mailbox`: adds
the SMTP mailbox probe (1 mailbox credit, charged only when the verdict
is not `unknown`).

<a id="scalar-schema-verdict"></a>

### Verdict

**Type:** `string`, possible values: `"valid", "invalid", "risky", "unknown"`

<a id="scalar-schema-reasoncode"></a>

### ReasonCode

**Type:** `string`

Stable reason for the verdict. New values may be added.

| Code                          | Verdict | Mode    | Meaning                                                                     |
| ----------------------------- | ------- | ------- | --------------------------------------------------------------------------- |
| `syntax_invalid`              | invalid | both    | Not a valid address in the supported ASCII profile.                         |
| `address_unsupported`         | unknown | both    | Internationalised (non-ASCII) address; not checked.                         |
| `domain_not_found`            | invalid | both    | The domain does not exist (NXDOMAIN).                                       |
| `domain_null_mx`              | invalid | both    | The domain declares it accepts no mail (null MX, RFC 7505).                 |
| `domain_no_mail_host`         | invalid | both    | No MX and no A/AAAA record.                                                 |
| `dns_temporary`               | unknown | both    | DNS failed temporarily. Not charged.                                        |
| `mailbox_not_checked`         | unknown | basic   | Domain can receive mail; mailbox not probed.                                |
| `disposable_domain`           | risky   | both    | Domain is on the disposable list.                                           |
| `legacy_domain`               | risky   | both    | Domain of a discontinued provider.                                          |
| `mailbox_exists`              | valid   | mailbox | Recipient accepted, random control rejected.                                |
| `mailbox_not_found`           | invalid | mailbox | Server says the recipient does not exist.                                   |
| `mailbox_disabled`            | risky   | mailbox | Server says the mailbox is disabled.                                        |
| `mailbox_full`                | risky   | mailbox | Server says the mailbox is full.                                            |
| `mailbox_forwarded`           | risky   | mailbox | Server announces forwarding (251).                                          |
| `provider_directory_rejected` | risky   | mailbox | Provider directory rejection (Microsoft 365) without confirmation.          |
| `catch_all`                   | risky   | mailbox | Server also accepts a random recipient.                                     |
| `catch_all_unresolved`        | unknown | mailbox | Recipient accepted but the catch-all control was inconclusive.              |
| `rejection_unconfirmed`       | unknown | mailbox | Rejected, but a known-good control was rejected too.                        |
| `probe_rate_limited`          | unknown | mailbox | Our hourly probe quota for that domain or server is exhausted.              |
| `probe_blocked`               | unknown | mailbox | The server refuses our probe (IP reputation, reverse DNS or sender policy). |
| `smtp_temporary`              | unknown | mailbox | Temporary rejection or greylisting.                                         |
| `smtp_unreachable`            | unknown | mailbox | No mail server could be reached.                                            |
| `smtp_tls_failed`             | unknown | mailbox | The advertised TLS session could not be verified.                           |
| `smtp_rejected`               | unknown | mailbox | Ambiguous or policy rejection that does not prove the mailbox is missing.   |

**Example:**

```json
"mailbox_exists"
```

<a id="scalar-schema-check"></a>

### Check

**Type:** `object`

One step that was actually executed, in order. Steps that did not run
are absent (for example `smtp` in `basic` mode, or `dns` after a syntax
failure).

| `name`                         | `status` values                                                                                                                             |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `syntax`                       | `ok`, `invalid`, `unsupported`                                                                                                              |
| `disposable`, `legacy`, `free` | `matched` (listed only when the domain matches)                                                                                             |
| `dns`                          | `mx`, `implicit_mx`, `nxdomain`, `null_mx`, `no_mail_host`, `temporary`                                                                     |
| `smtp`                         | `accepted`, `missing`, `provider_missing`, `disabled`, `full`, `forwarded`, `temporary`, `limited`, `unreachable`, `tls_failed`, `rejected` |
| `catch_all`                    | same values as `smtp`, for the random control recipient                                                                                     |

- **`name` (required)**: `string`, possible values: `"syntax", "disposable", "legacy", "free", "dns", "smtp", "catch_all"`
- **`status` (required)**: `string`

  Outcome of the step. New values may be added.

<a id="scalar-example-1"></a>

**Generated example:**

```json
{
  "name": "syntax",
  "status": ""
}
```

<a id="scalar-schema-flags"></a>

### Flags

**Type:** `object`

- **`catch_all` (required)**: `boolean | null`

  `true`: the server also accepted a random recipient. `false`: it
  rejected the random recipient. `null`: not tested (`basic` mode,
  recipient not accepted) or inconclusive.
- **`disposable` (required)**: `boolean`

  The domain (or a parent domain) is on the disposable-email list.
- **`free` (required)**: `boolean`

  The domain is a free webmail provider. Informational; does not change the verdict.

<a id="scalar-example-2"></a>

**Generated example:**

```json
{
  "disposable": true,
  "free": true,
  "catch_all": null
}
```

<a id="scalar-schema-mxrecord"></a>

### MxRecord

**Type:** `object`

- **`host` (required)**: `string`
- **`preference` (required)**: `integer`, minimum: `0`, maximum: `65535`

<a id="scalar-example-3"></a>

**Generated example:**

```json
{
  "host": "",
  "preference": 0
}
```

<a id="scalar-schema-smtpevidence"></a>

### SmtpEvidence

**Type:** `object`

What the recipient's server answered to `RCPT TO` for this address.

- **`code` (required)**: `integer | null`

  SMTP reply code, when a reply was received.
- **`enhanced_code` (required)**: `string | null`

  Enhanced status code (RFC 3463), when present.
- **`mx` (required)**: `string | null`

  Mail server that answered.
- **`tls` (required)**: `boolean`

  Whether the session used verified TLS.

<a id="scalar-example-4"></a>

**Generated example:**

```json
{
  "mx": null,
  "code": null,
  "enhanced_code": null,
  "tls": true
}
```

<a id="scalar-schema-verification"></a>

### Verification

**Type:** `object`

- **`cached` (required)**: `boolean`

  The result was served from a recent check; `checked_at` is the time of that check.
- **`checked_at` (required)**: `string`, format: `date-time`
- **`checks` (required)**: array of [Check](#scalar-schema-check)
- **`credits_charged` (required)**: `integer`, possible values: `0, 1`

  Credits of the type of `mode` charged for this result.
- **`email` (required)**: `string`

  The address as verified, trimmed and lower-cased.
- **`flags` (required)**: [Flags](#scalar-schema-flags)
- **`id` (required)**: `string`, pattern: `^ver_[a-f0-9]{32}$`
- **`livemode` (required)**: `boolean`
- **`mode` (required)**: `string`, possible values: `"basic", "mailbox"`

  `basic`: syntax, domain lists and DNS (1 basic credit). `mailbox`: adds
  the SMTP mailbox probe (1 mailbox credit, charged only when the verdict
  is not `unknown`).
- **`mx` (required)**: array of [MxRecord](#scalar-schema-mxrecord)

  Mail servers of the domain, as resolved. Empty when DNS was not resolved.
- **`object` (required)**: `string`, possible values: `"verification"`
- **`reason` (required)**: `string`

  Human-readable explanation of `reason_code`, in the language of `Accept-Language`.
- **`reason_code` (required)**: `string`

  Stable reason for the verdict. New values may be added.
  | Code                          | Verdict | Mode    | Meaning                                                                     |
  | ----------------------------- | ------- | ------- | --------------------------------------------------------------------------- |
  | `syntax_invalid`              | invalid | both    | Not a valid address in the supported ASCII profile.                         |
  | `address_unsupported`         | unknown | both    | Internationalised (non-ASCII) address; not checked.                         |
  | `domain_not_found`            | invalid | both    | The domain does not exist (NXDOMAIN).                                       |
  | `domain_null_mx`              | invalid | both    | The domain declares it accepts no mail (null MX, RFC 7505).                 |
  | `domain_no_mail_host`         | invalid | both    | No MX and no A/AAAA record.                                                 |
  | `dns_temporary`               | unknown | both    | DNS failed temporarily. Not charged.                                        |
  | `mailbox_not_checked`         | unknown | basic   | Domain can receive mail; mailbox not probed.                                |
  | `disposable_domain`           | risky   | both    | Domain is on the disposable list.                                           |
  | `legacy_domain`               | risky   | both    | Domain of a discontinued provider.                                          |
  | `mailbox_exists`              | valid   | mailbox | Recipient accepted, random control rejected.                                |
  | `mailbox_not_found`           | invalid | mailbox | Server says the recipient does not exist.                                   |
  | `mailbox_disabled`            | risky   | mailbox | Server says the mailbox is disabled.                                        |
  | `mailbox_full`                | risky   | mailbox | Server says the mailbox is full.                                            |
  | `mailbox_forwarded`           | risky   | mailbox | Server announces forwarding (251).                                          |
  | `provider_directory_rejected` | risky   | mailbox | Provider directory rejection (Microsoft 365) without confirmation.          |
  | `catch_all`                   | risky   | mailbox | Server also accepts a random recipient.                                     |
  | `catch_all_unresolved`        | unknown | mailbox | Recipient accepted but the catch-all control was inconclusive.              |
  | `rejection_unconfirmed`       | unknown | mailbox | Rejected, but a known-good control was rejected too.                        |
  | `probe_rate_limited`          | unknown | mailbox | Our hourly probe quota for that domain or server is exhausted.              |
  | `probe_blocked`               | unknown | mailbox | The server refuses our probe (IP reputation, reverse DNS or sender policy). |
  | `smtp_temporary`              | unknown | mailbox | Temporary rejection or greylisting.                                         |
  | `smtp_unreachable`            | unknown | mailbox | No mail server could be reached.                                            |
  | `smtp_tls_failed`             | unknown | mailbox | The advertised TLS session could not be verified.                           |
  | `smtp_rejected`               | unknown | mailbox | Ambiguous or policy rejection that does not prove the mailbox is missing.   |
- **`retry_at` (required)**: `string | null`, format: `date-time`

  When a temporary result can be verified again. In batches this is handled for you.
- **`smtp` (required)**: [SmtpEvidence](#scalar-schema-smtpevidence) | `null`

  `null` in `basic` mode or when the probe did not run.
- **`verdict` (required)**: `string`, possible values: `"valid", "invalid", "risky", "unknown"`

<a id="scalar-example-5"></a>

**Generated example:**

```json
{
  "id": "",
  "object": "verification",
  "livemode": true,
  "email": "",
  "mode": "basic",
  "verdict": "valid",
  "reason_code": "mailbox_exists",
  "reason": "",
  "flags": {
    "disposable": true,
    "free": true,
    "catch_all": null
  },
  "checks": [
    {
      "name": "syntax",
      "status": ""
    }
  ],
  "mx": [
    {
      "host": "",
      "preference": 0
    }
  ],
  "smtp": {
    "mx": null,
    "code": null,
    "enhanced_code": null,
    "tls": true
  },
  "cached": true,
  "credits_charged": 0,
  "checked_at": "2026-11-17T09:50:00.000Z",
  "retry_at": null
}
```

<a id="scalar-schema-verifyrequest"></a>

### VerifyRequest

**Type:** `object`

- **`email` (required)**: `string`, minLength: `1`, maxLength: `1024`

  Address to verify. Leading/trailing spaces and case are normalised.
- **`mode`**: `string`, possible values: `"basic", "mailbox"`, default: `"basic"`

  `basic`: syntax, domain lists and DNS (1 basic credit). `mailbox`: adds
  the SMTP mailbox probe (1 mailbox credit, charged only when the verdict
  is not `unknown`).

<a id="scalar-example-6"></a>

**Generated example:**

```json
{
  "email": "",
  "mode": "basic"
}
```

<a id="scalar-schema-batchcreaterequest"></a>

### BatchCreateRequest

**Type:** `object`

- **`emails` (required)**: `array`, minItems: `1`, maxItems: `10000`

  **Items:**

  `string`, maxLength: `1024`
- **`mode`**: `string`, possible values: `"basic", "mailbox"`, default: `"basic"`

  `basic`: syntax, domain lists and DNS (1 basic credit). `mailbox`: adds
  the SMTP mailbox probe (1 mailbox credit, charged only when the verdict
  is not `unknown`).
- **`name`**: `string`, maxLength: `120`

  Optional label shown in the dashboard.

<a id="scalar-example-7"></a>

**Generated example:**

```json
{
  "emails": [
    ""
  ],
  "mode": "basic",
  "name": ""
}
```

<a id="scalar-schema-batchcsvupload"></a>

### BatchCsvUpload

**Type:** `object`

- **`file` (required)**: `string`

  UTF-8 CSV with a header row. Up to 10 MB and 100,000 data rows.
- **`delimiter`**: `string`, possible values: `"comma", "semicolon", "tab"`, default: `"comma"`
- **`email_column`**: `string`, default: `"email"`

  Exact name of the header that holds the addresses.
- **`mode`**: `string`, possible values: `"basic", "mailbox"`, default: `"basic"`

  `basic`: syntax, domain lists and DNS (1 basic credit). `mailbox`: adds
  the SMTP mailbox probe (1 mailbox credit, charged only when the verdict
  is not `unknown`).
- **`name`**: `string`, maxLength: `120`

  Optional label shown in the dashboard.

<a id="scalar-example-8"></a>

**Generated example:**

```json
{
  "file": "",
  "mode": "basic",
  "email_column": "email",
  "delimiter": "comma",
  "name": ""
}
```

<a id="scalar-schema-batchstatus"></a>

### BatchStatus

**Type:** `string`, possible values: `"queued", "processing", "completed", "canceled", "failed"`

`queued` → `processing` → `completed`. `canceled` after
`POST /batches/{batch_id}/cancel`. `failed` only for an internal error;
reserved credits are returned.

<a id="scalar-schema-batch"></a>

### Batch

**Type:** `object`

- **`created_at` (required)**: `string`, format: `date-time`
- **`credits` (required)**: `object`
  - **`charged` (required)**: `integer`

    Credits charged so far.
  - **`reserved` (required)**: `integer`

    Credits still held for rows without a final result.
  - **`type` (required)**: `string`, possible values: `"basic", "mailbox"`

    `basic`: syntax, domain lists and DNS (1 basic credit). `mailbox`: adds
    the SMTP mailbox probe (1 mailbox credit, charged only when the verdict
    is not `unknown`).
- **`deadline_at` (required)**: `string | null`, format: `date-time`

  Processing deadline (6 days after start). Rows unresolved by then end as `unknown`, free of charge.
- **`finished_at` (required)**: `string | null`, format: `date-time`

  When the batch reached `completed`, `canceled` or `failed`.
- **`id` (required)**: `string`, pattern: `^bat_[a-f0-9]{32}$`
- **`livemode` (required)**: `boolean`
- **`mode` (required)**: `string`, possible values: `"basic", "mailbox"`

  `basic`: syntax, domain lists and DNS (1 basic credit). `mailbox`: adds
  the SMTP mailbox probe (1 mailbox credit, charged only when the verdict
  is not `unknown`).
- **`name` (required)**: `string | null`
- **`object` (required)**: `string`, possible values: `"batch"`
- **`processed` (required)**: `integer`

  Rows with a final result.
- **`results_expire_at` (required)**: `string | null`, format: `date-time`

  When inputs and results are deleted (30 days after `finished_at`).
- **`source` (required)**: `string`, possible values: `"json", "csv"`
- **`started_at` (required)**: `string | null`, format: `date-time`
- **`status` (required)**: `string`, possible values: `"queued", "processing", "completed", "canceled", "failed"`

  `queued` → `processing` → `completed`. `canceled` after
  `POST /batches/{batch_id}/cancel`. `failed` only for an internal error;
  reserved credits are returned.
- **`summary` (required)**: `object`

  Final results so far, by verdict (rows, including duplicates).
  - **`invalid` (required)**: `integer`
  - **`risky` (required)**: `integer`
  - **`unknown` (required)**: `integer`
  - **`valid` (required)**: `integer`
- **`total` (required)**: `integer`

  Rows accepted, including duplicates.
- **`unique` (required)**: `integer`

  Distinct addresses after normalisation.

<a id="scalar-example-9"></a>

**Generated example:**

```json
{
  "id": "",
  "object": "batch",
  "livemode": true,
  "name": null,
  "source": "json",
  "mode": "basic",
  "status": "queued",
  "total": 1,
  "unique": 1,
  "processed": 1,
  "summary": {
    "valid": 1,
    "invalid": 1,
    "risky": 1,
    "unknown": 1
  },
  "credits": {
    "type": "basic",
    "reserved": 1,
    "charged": 1
  },
  "created_at": "2026-11-17T09:50:00.000Z",
  "started_at": null,
  "finished_at": null,
  "deadline_at": null,
  "results_expire_at": null
}
```

<a id="scalar-schema-batchlist"></a>

### BatchList

**Type:** `object`

- **`data` (required)**: array of [Batch](#scalar-schema-batch)
- **`has_more` (required)**: `boolean`
- **`next_cursor` (required)**: `string | null`
- **`object` (required)**: `string`, possible values: `"list"`

<a id="scalar-example-10"></a>

**Generated example:**

```json
{
  "object": "list",
  "data": [
    {
      "id": "",
      "object": "batch",
      "livemode": true,
      "name": null,
      "source": "json",
      "mode": "basic",
      "status": "queued",
      "total": 1,
      "unique": 1,
      "processed": 1,
      "summary": {
        "valid": 1,
        "invalid": 1,
        "risky": 1,
        "unknown": 1
      },
      "credits": {
        "type": "basic",
        "reserved": 1,
        "charged": 1
      },
      "created_at": "2026-11-17T09:50:00.000Z",
      "started_at": null,
      "finished_at": null,
      "deadline_at": null,
      "results_expire_at": null
    }
  ],
  "has_more": true,
  "next_cursor": null
}
```

<a id="scalar-schema-batchresult"></a>

### BatchResult

**All of:**

- `object`
  - **`duplicate` (required)**: `boolean`

    `true` when an earlier row holds the same address; duplicates are never charged.
  - **`input` (required)**: `string`

    The value exactly as submitted.
  - **`row` (required)**: `integer`, minimum: `1`

    1-based position in `emails`, or data row number in the CSV (header excluded).
- [Verification](#scalar-schema-verification)

<a id="scalar-schema-batchresultlist"></a>

### BatchResultList

**Type:** `object`

- **`data` (required)**: array of [BatchResult](#scalar-schema-batchresult)
- **`has_more` (required)**: `boolean`
- **`next_cursor` (required)**: `string | null`
- **`object` (required)**: `string`, possible values: `"list"`

<a id="scalar-example-11"></a>

**Generated example:**

```json
{
  "object": "list",
  "data": [
    {
      "row": 1,
      "input": "",
      "duplicate": true,
      "id": "",
      "object": "verification",
      "livemode": true,
      "email": "",
      "mode": "basic",
      "verdict": "valid",
      "reason_code": "mailbox_exists",
      "reason": "",
      "flags": {
        "disposable": true,
        "free": true,
        "catch_all": null
      },
      "checks": [
        {
          "name": "syntax",
          "status": ""
        }
      ],
      "mx": [
        {
          "host": "",
          "preference": 0
        }
      ],
      "smtp": {
        "mx": null,
        "code": null,
        "enhanced_code": null,
        "tls": true
      },
      "cached": true,
      "credits_charged": 0,
      "checked_at": "2026-11-17T09:50:00.000Z",
      "retry_at": null
    }
  ],
  "has_more": true,
  "next_cursor": null
}
```

<a id="scalar-schema-usage"></a>

### Usage

**Type:** `object`

- **`credits` (required)**: `object`
  - **`basic` (required)**: `object`
    - **`granted` (required)**: `integer`

      Monthly allowance of the current period.
    - **`remaining` (required)**: `integer`
    - **`reserved` (required)**: `integer`

      Held by running batches.
    - **`resets_at` (required)**: `string`, format: `date-time`
  - **`mailbox` (required)**: `object`
    - **`next_expiry` (required)**: `object | null`

      The next credits to expire, or `null` when none expire.
      - **`amount` (required)**: `integer`
      - **`at` (required)**: `string`, format: `date-time`
    - **`remaining` (required)**: `integer`
    - **`reserved` (required)**: `integer`

      Held by running batches.
- **`livemode` (required)**: `boolean`
- **`object` (required)**: `string`, possible values: `"usage"`
- **`period` (required)**: `object`

  Current billing period of the basic allowance.
  - **`end` (required)**: `string`, format: `date-time`
  - **`start` (required)**: `string`, format: `date-time`
- **`usage` (required)**: `object`

  Activity in the current period.
  - **`basic` (required)**: [UsageCounters](#scalar-schema-usagecounters)
  - **`mailbox` (required)**: [UsageCounters](#scalar-schema-usagecounters)

<a id="scalar-example-12"></a>

**Generated example:**

```json
{
  "object": "usage",
  "livemode": true,
  "credits": {
    "basic": {
      "remaining": 1,
      "reserved": 1,
      "granted": 1,
      "resets_at": "2026-11-17T09:50:00.000Z"
    },
    "mailbox": {
      "remaining": 1,
      "reserved": 1,
      "next_expiry": {
        "amount": 1,
        "at": "2026-11-17T09:50:00.000Z"
      }
    }
  },
  "period": {
    "start": "2026-11-17T09:50:00.000Z",
    "end": "2026-11-17T09:50:00.000Z"
  },
  "usage": {
    "basic": {
      "verifications": 1,
      "credits_charged": 1
    },
    "mailbox": {
      "verifications": 1,
      "credits_charged": 1
    }
  }
}
```

<a id="scalar-schema-usagecounters"></a>

### UsageCounters

**Type:** `object`

- **`credits_charged` (required)**: `integer`
- **`verifications` (required)**: `integer`

  Verifications completed, single and batch.

<a id="scalar-example-13"></a>

**Generated example:**

```json
{
  "verifications": 1,
  "credits_charged": 1
}
```

<a id="scalar-schema-account"></a>

### Account

**Type:** `object`

- **`api_key` (required)**: `object`

  The key used for this request. The secret is never returned.
  - **`created_at` (required)**: `string`, format: `date-time`
  - **`id` (required)**: `string`, pattern: `^key_[a-f0-9]{16}$`
  - **`name` (required)**: `string`
  - **`prefix` (required)**: `string`

    First characters of the key, as shown in the dashboard.
- **`created_at` (required)**: `string`, format: `date-time`
- **`id` (required)**: `string`, pattern: `^org_[a-f0-9]{16}$`
- **`limits` (required)**: `object`
  - **`max_batch_size` (required)**: `integer`

    Maximum rows per batch for this plan.
  - **`max_concurrent_batches` (required)**: `integer`

    Batches that may be `queued` or `processing` at once.
  - **`modes` (required)**: `array`

    **Items:**

    `string`, possible values: `"basic", "mailbox"`

    `basic`: syntax, domain lists and DNS (1 basic credit). `mailbox`: adds
    the SMTP mailbox probe (1 mailbox credit, charged only when the verdict
    is not `unknown`).
  - **`requests_per_minute` (required)**: `integer`
- **`livemode` (required)**: `boolean`

  `false` when the request used a `sk_test_…` key.
- **`name` (required)**: `string`
- **`object` (required)**: `string`, possible values: `"account"`
- **`plan` (required)**: `object`
  - **`id` (required)**: `string`, possible values: `"free", "basic", "basic_plus"`
  - **`status` (required)**: `string`, possible values: `"active", "past_due", "canceled"`

<a id="scalar-example-14"></a>

**Generated example:**

```json
{
  "id": "",
  "object": "account",
  "livemode": true,
  "name": "",
  "plan": {
    "id": "free",
    "status": "active"
  },
  "api_key": {
    "id": "",
    "name": "",
    "prefix": "",
    "created_at": "2026-11-17T09:50:00.000Z"
  },
  "limits": {
    "requests_per_minute": 1,
    "max_batch_size": 1,
    "max_concurrent_batches": 1,
    "modes": [
      "basic"
    ]
  },
  "created_at": "2026-11-17T09:50:00.000Z"
}
```

<a id="scalar-schema-error"></a>

### Error

**Type:** `object`

- **`code` (required)**: `string`

  Stable machine-readable code (see the table in the API description). New values may be added.
- **`message` (required)**: `string`

  Human-readable explanation. Do not parse it.
- **`request_id` (required)**: `string`

  Same value as the `X-Request-Id` header.
- **`type` (required)**: `string`, possible values: `"invalid_request", "authentication", "payment_required", "permission", "not_found", "conflict", "rate_limit", "api_error"`
- **`param`**: `string`

  Request field the error refers to, when there is one.

<a id="scalar-example-15"></a>

**Generated example:**

```json
{
  "type": "invalid_request",
  "code": "",
  "message": "",
  "param": "",
  "request_id": ""
}
```

<a id="scalar-schema-errorresponse"></a>

### ErrorResponse

**Type:** `object`

- **`error` (required)**: [Error](#scalar-schema-error)

<a id="scalar-example-16"></a>

**Generated example:**

```json
{
  "error": {
    "type": "invalid_request",
    "code": "",
    "message": "",
    "param": "",
    "request_id": ""
  }
}
```

<a id="scalar-schema-eventbase"></a>

### EventBase

**Type:** `object`

- **`created_at` (required)**: `string`, format: `date-time`
- **`id` (required)**: `string`, pattern: `^evt_[a-f0-9]{32}$`

  Unique per event; identical across retries. Use it to deduplicate.
- **`livemode` (required)**: `boolean`
- **`object` (required)**: `string`, possible values: `"event"`
- **`type` (required)**: `string`

<a id="scalar-example-17"></a>

**Generated example:**

```json
{
  "id": "",
  "object": "event",
  "type": "",
  "livemode": true,
  "created_at": "2026-11-17T09:50:00.000Z"
}
```

<a id="scalar-schema-batchcompletedevent"></a>

### BatchCompletedEvent

**All of:**

- [EventBase](#scalar-schema-eventbase)
- `object`
  - **`data` (required)**: `object`
    - **`batch` (required)**: [Batch](#scalar-schema-batch)
  - **`type` (required)**: `string`, possible values: `"batch.completed"`

<a id="scalar-schema-creditslowevent"></a>

### CreditsLowEvent

**All of:**

- [EventBase](#scalar-schema-eventbase)
- `object`
  - **`data` (required)**: `object`
    - **`credit_type` (required)**: `string`, possible values: `"basic", "mailbox"`

      `basic`: syntax, domain lists and DNS (1 basic credit). `mailbox`: adds
      the SMTP mailbox probe (1 mailbox credit, charged only when the verdict
      is not `unknown`).
    - **`remaining` (required)**: `integer`
    - **`threshold` (required)**: `integer`
  - **`type` (required)**: `string`, possible values: `"credits.low"`

