# Documentación de SalchiMail

> SalchiMail es una API de verificación de emails que nunca envía correo: la comprobación de buzón se detiene en `RCPT TO`. Verifica una dirección por petición o limpia listas por lotes. Cada resultado trae un veredicto (`valid`, `invalid`, `risky`, `unknown`) y un `reason_code` estable.

- URL base: `https://api.salchimail.com/v1`. JSON sobre HTTPS.
- Autenticación: `Authorization: Bearer sk_live_…` (o `sk_test_…` en modo de pruebas). Las claves son secretos de servidor.
- Dos modos: `basic` (sintaxis, listas de dominios, DNS) y `mailbox` (añade el sondeo SMTP `RCPT TO`). Cada uno tiene su propio saldo de créditos.
- Nunca trates `unknown` como `invalid`.

---

# Inicio rápido

De cero a tu primera dirección verificada en menos de cinco minutos. Necesitas una cuenta de SalchiMail y una terminal.

## 1. Crea una clave de API

Entra en el panel, en [app.salchimail.com](https://app.salchimail.com), y crea una clave de API. La clave se muestra **una sola vez**: cópiala ahora.

- Las claves `sk_live_…` hacen verificaciones reales y consumen créditos.
- Las claves `sk_test_…` devuelven resultados simulados y nunca consumen créditos. Consulta [Entorno de pruebas](https://docs.salchimail.com/es/entorno-de-pruebas.md).

Guarda la clave en una variable de entorno. Es un secreto: úsala desde tu servidor, nunca desde un navegador ni una aplicación móvil.

```bash
export SALCHIMAIL_API_KEY="sk_live_tu_clave"
```

## 2. Verifica una dirección

Cambia `ana@example.com` por una dirección que conozcas y lanza la petición. Aquí `mode` es `mailbox`, así que se pregunta al servidor de correo si el buzón existe. No se envía ningún email.

**curl**

```bash
curl https://api.salchimail.com/v1/verify \
  -H "Authorization: Bearer $SALCHIMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "ana@example.com", "mode": "mailbox"}'
```

**JavaScript / TypeScript**

```js
const response = await fetch("https://api.salchimail.com/v1/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SALCHIMAIL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "ana@example.com", mode: "mailbox" }),
});
const result = await response.json();

if (!response.ok) {
  throw new Error(`${result.error.code}: ${result.error.message}`);
}
console.log(result.verdict, result.reason_code);
```

**Python**

```python
import json
import os
import urllib.error
import urllib.request

request = urllib.request.Request(
    "https://api.salchimail.com/v1/verify",
    data=json.dumps({"email": "ana@example.com", "mode": "mailbox"}).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['SALCHIMAIL_API_KEY']}",
        "Content-Type": "application/json",
    },
)
try:
    with urllib.request.urlopen(request, timeout=40) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    problem = json.load(error)["error"]
    raise SystemExit(f"{problem['code']}: {problem['message']}")

print(result["verdict"], result["reason_code"])
```

**PHP**

```php
<?php
$ch = curl_init("https://api.salchimail.com/v1/verify");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 40,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("SALCHIMAIL_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode(["email" => "ana@example.com", "mode" => "mailbox"]),
]);
$body = curl_exec($ch);
if ($body === false) {
    fwrite(STDERR, "Request failed: " . curl_error($ch) . "\n");
    exit(1);
}
$result = json_decode($body, true);

if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 200) {
    fwrite(STDERR, "{$result['error']['code']}: {$result['error']['message']}\n");
    exit(1);
}
echo "{$result['verdict']} {$result['reason_code']}\n";
```

**Go**

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
	"time"
)

type verification struct {
	Verdict    string `json:"verdict"`
	ReasonCode string `json:"reason_code"`
	Error      *struct {
		Code    string `json:"code"`
		Message string `json:"message"`
	} `json:"error"`
}

func main() {
	payload, _ := json.Marshal(map[string]string{"email": "ana@example.com", "mode": "mailbox"})
	req, _ := http.NewRequest("POST", "https://api.salchimail.com/v1/verify", bytes.NewReader(payload))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SALCHIMAIL_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{Timeout: 40 * time.Second}
	res, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()

	var result verification
	if err := json.NewDecoder(res.Body).Decode(&result); err != nil {
		log.Fatal(err)
	}
	if result.Error != nil {
		log.Fatalf("%s: %s", result.Error.Code, result.Error.Message)
	}
	fmt.Println(result.Verdict, result.ReasonCode)
}
```

La comprobación de buzón habla con el servidor de correo del destinatario y puede tardar hasta 30 segundos: dale a tu cliente HTTP un tiempo de espera superior.

## 3. Lee el resultado

La respuesta es un objeto de verificación:

```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
}
```

Empieza por `verdict` y lee después `reason_code` para saber el porqué:

| `verdict` | Qué significa | Qué hacer |
| --- | --- | --- |
| `valid` | El servidor acepta a este destinatario y rechaza uno aleatorio | Envía |
| `invalid` | Sintaxis incorrecta, un dominio que no puede recibir correo o un «no existe ese destinatario» claro | No envíes |
| `risky` | Servidor que lo acepta todo, dominio desechable, buzón lleno o desactivado, y casos parecidos | Decide según `reason_code` |
| `unknown` | La comprobación no pudo terminar o no se hizo | **No lo trates como `invalid`**. Reintenta después de `retry_at` cuando venga informado |

`credits_charged` te dice cuánto ha costado la llamada. En modo `mailbox`, un resultado `unknown` es gratis. La lista completa está en [Veredictos y reason codes](https://docs.salchimail.com/es/veredictos.md).

## 4. Elige el modo para tu caso

- **Un formulario de registro**: usa `"mode": "basic"`. Comprueba sintaxis, listas de dominios y DNS en bastante menos de un segundo. Consulta [Verificación en el registro](https://docs.salchimail.com/es/verificacion-en-registro.md).
- **Una lista**: envíala como lote en lugar de hacer una petición por dirección. Consulta [Limpieza de listas por lotes](https://docs.salchimail.com/es/lotes.md).

## Siguientes pasos

- [Autenticación](https://docs.salchimail.com/es/autenticacion.md): tipos de clave, rotación y qué significa un `401`.
- [Idempotencia](https://docs.salchimail.com/es/idempotencia.md): reintenta un `POST` sin riesgo.
- [Límites y errores](https://docs.salchimail.com/es/limites-y-errores.md): límites de peticiones y todos los códigos de error.
- [Referencia de la API](https://docs.salchimail.com/reference.md): todos los endpoints, campos y ejemplos.

Source: https://docs.salchimail.com/es/inicio-rapido

---

# Autenticación

Cada petición lleva una clave de API secreta en la cabecera `Authorization`:

```http
Authorization: Bearer sk_live_…
```

## Claves

Las claves se crean en el panel, en [app.salchimail.com](https://app.salchimail.com). Una clave se muestra una sola vez, al crearla, y SalchiMail solo guarda su hash. Si pierdes una clave, crea otra.

| Prefijo | Modo | Comportamiento |
| --- | --- | --- |
| `sk_live_` | Real | Verificaciones reales. Consume créditos |
| `sk_test_` | Pruebas | Resultados simulados, sin créditos. Consulta [Entorno de pruebas](https://docs.salchimail.com/es/entorno-de-pruebas.md) |

Una clave pertenece a tu organización, no a una persona. Crea una clave por aplicación o entorno y ponle un nombre que reconozcas más adelante.

## Las claves, siempre en el servidor

Una clave es un secreto con acceso a tus créditos.

- Llama a la API desde tu backend. Nunca incluyas una clave en una página web, una aplicación móvil o un repositorio público.
- La API no envía cabeceras CORS, así que una petición hecha desde un navegador fallará por diseño.
- Carga la clave desde una variable de entorno o un gestor de secretos, no desde el código fuente.

## Comprueba qué clave estás usando

`GET /account` devuelve la organización, el plan, los límites y la clave con la que se hizo la petición. El secreto nunca se devuelve, solo su `prefix`.

```bash
curl https://api.salchimail.com/v1/account \
  -H "Authorization: Bearer $SALCHIMAIL_API_KEY"
```

```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"
}
```

`livemode` es `false` cuando la petición usó una clave `sk_test_`.

## Rota una clave

1. Crea una clave nueva en el panel.
2. Despliégala en tu aplicación.
3. Revoca la clave antigua. Desde ese momento responde `401 revoked_api_key`.

## Errores de autenticación

Una petición sin una clave utilizable responde `401` con la cabecera `WWW-Authenticate: Bearer`:

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

| HTTP | `code` | Significado | Qué hacer |
| --- | --- | --- | --- |
| 401 | `missing_api_key` | Falta la cabecera `Authorization: Bearer` | Envía la cabecera en todas las peticiones |
| 401 | `invalid_api_key` | La clave no existe | Revisa si está cortada o mal copiada |
| 401 | `revoked_api_key` | La clave se revocó en el panel | Usa una clave vigente |
| 403 | `mode_not_allowed` | La cuenta no puede usar ese `mode` | Consulta `limits.modes` en `GET /account` |
| 403 | `account_suspended` | La cuenta está suspendida | Escribe a [hola@salchimail.com](mailto:hola@salchimail.com) |

La forma de todos los errores se describe en [Límites y errores](https://docs.salchimail.com/es/limites-y-errores.md).

Source: https://docs.salchimail.com/es/autenticacion

---

# Entorno de pruebas

Una clave que empieza por `sk_test_` funciona en modo de pruebas: **no se hace ninguna verificación real y no se consumen créditos**. Úsala para construir tu integración y en tus tests automáticos.

## Veredictos predecibles

La sintaxis se sigue comprobando. Después, el veredicto lo decide la parte local de la dirección (el texto anterior a `@`):

| Dirección | `verdict` | `reason_code` |
| --- | --- | --- |
| `valid@…` | `valid` | |
| `invalid@…` | `invalid` | |
| `risky@…` | `risky` | `catch_all` |
| `disposable@…` | `risky` | `disposable_domain` |
| Cualquier otra | `unknown` | |

El contrato solo fija el `reason_code` en los dos casos `risky`. En los demás, comprueba el `verdict`.

```bash
curl https://api.salchimail.com/v1/verify \
  -H "Authorization: Bearer $SALCHIMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "risky@example.com", "mode": "mailbox"}'
```

## En qué se diferencia del modo real

- Los objetos llevan `"livemode": false`, incluidos `GET /account` y `GET /usage`.
- No se cobran ni se reservan créditos.
- Los lotes de prueba terminan en segundos, así que puedes recorrer todo el [flujo de lotes](https://docs.salchimail.com/es/lotes.md): crear, consultar y descargar.
- Nunca se contacta con el servidor de correo de la dirección.

Todo lo demás es el mismo contrato: los mismos endpoints, campos, [errores](https://docs.salchimail.com/es/limites-y-errores.md) y reglas de [idempotencia](https://docs.salchimail.com/es/idempotencia.md).

## Uso recomendado

- Ten una clave `sk_test_` en desarrollo y en integración continua, y la clave `sk_live_` solo en producción.
- Cubre cada rama de tu código con la dirección que le corresponde: un test con `valid@`, otro con `invalid@`, otro con `risky@` y otro con una dirección que dé `unknown`.
- Comprueba `livemode` en tus tests para asegurarte de que nunca gastan créditos reales.

Source: https://docs.salchimail.com/es/entorno-de-pruebas

---

# Verificación en el registro

Frena erratas, dominios muertos y direcciones desechables en el formulario, sin hacer esperar a los usuarios reales.

## El patrón recomendado

1. El formulario envía los datos a **tu servidor**. La clave de API nunca llega al navegador.
2. Tu servidor llama a `POST /verify` con `"mode": "basic"` y un tiempo de espera corto.
3. Rechaza los `invalid`, aplica tu política a los dominios desechables y acepta el resto.
4. Si la llamada falla o se agota el tiempo, **acepta el registro** y verifica después.
5. Envía tu email de confirmación como siempre.

**JavaScript / TypeScript**

```js
// Decides what to do with the address typed in a sign-up form. Run it on your server.
async function checkSignupEmail(email) {
  let response;
  try {
    response = await fetch("https://api.salchimail.com/v1/verify", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.SALCHIMAIL_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ email, mode: "basic" }),
      signal: AbortSignal.timeout(3000), // never keep the form waiting
    });
  } catch {
    return "accept"; // timeout or network error: fail open and verify later
  }
  if (!response.ok) {
    // 429, 402 or 5xx must not cost you a sign-up. A 400 or 401 is a bug on your side: log it.
    console.error("SalchiMail answered", response.status, response.headers.get("X-Request-Id"));
    return "accept";
  }

  const { verdict, reason_code } = await response.json();
  if (verdict === "invalid") return "reject"; // bad syntax or a domain that cannot receive mail
  if (reason_code === "disposable_domain") return "reject"; // your policy: could also be "review"
  return "accept"; // "unknown" is the normal basic answer: the domain can receive mail
}

console.log(await checkSignupEmail("ana@example.com"));
```

## Tiempos

| Modo | Respuesta habitual | Tiempo de espera recomendado | Dónde ejecutarlo |
| --- | --- | --- | --- |
| `basic` | Bastante menos de un segundo | 3 segundos | En línea, mientras se envía el formulario |
| `mailbox` | Hasta 30 segundos | Más de 30 segundos | En una tarea en segundo plano, después del registro |

`basic` nunca contacta con el servidor de correo, por eso es rápido. `mailbox` habla con el servidor del destinatario: si no termina en 30 segundos, la API responde `503 verification_timeout` y no cobra nada. No dejes un formulario de registro esperando a una comprobación de buzón.

Si quieres la certeza del buzón para los usuarios nuevos, lanza una verificación `mailbox` desde una tarea en segundo plano cuando la cuenta ya exista y actúa según el resultado antes de tu primera campaña.

## Qué hacer con cada resultado

| Resultado en modo `basic` | Significado | Acción recomendada |
| --- | --- | --- |
| `invalid` · `syntax_invalid` | No es una dirección de email | Pide al usuario que la corrija |
| `invalid` · `domain_not_found`, `domain_null_mx`, `domain_no_mail_host` | El dominio no puede recibir correo. Suele ser una errata | Pide al usuario que revise el dominio |
| `risky` · `disposable_domain` | Dirección de usar y tirar | Recházala o pide otra dirección, según tu política |
| `risky` · `legacy_domain` | Dominio de un proveedor que ya no existe | Pide otra dirección |
| `unknown` · `mailbox_not_checked` | El dominio puede recibir correo. Es la respuesta normal | Acepta |
| `unknown` · `dns_temporary`, `address_unsupported` | La comprobación no se pudo hacer | Acepta |

`flags.free` te dice que el dominio es de un proveedor de correo gratuito. Es informativo y no cambia el veredicto.

Para mostrar un mensaje al usuario, asocia cada `reason_code` a tu propio texto. `reason` es una explicación ya redactada en inglés o, con la cabecera `Accept-Language: es`, en español.

## Reglas para no perder registros

- **Ante un fallo, deja pasar.** Un tiempo de espera agotado, un `429`, un `402` o un `5xx` nunca deben costarte un usuario real. Acepta y verifica después.
- **Nunca trates `unknown` como `invalid`.** En modo `basic`, `unknown` es la respuesta para cualquier dominio sano.
- **Mantén tu email de confirmación.** `valid` dice que el servidor acepta la dirección. No demuestra que la persona sea su dueña ni que la lea.
- **Los reenvíos del formulario salen baratos.** Verificar otra vez la misma dirección en 30 días en modo `basic` es gratis: a quien envía el formulario dos veces se le cobra una.
- **Los reintentos son seguros** con una [`Idempotency-Key`](https://docs.salchimail.com/es/idempotencia.md).

Consulta [Veredictos y reason codes](https://docs.salchimail.com/es/veredictos.md) para la lista completa y [Límites y errores](https://docs.salchimail.com/es/limites-y-errores.md) para los límites de peticiones.

Source: https://docs.salchimail.com/es/verificacion-en-registro

---

# Limpieza de listas por lotes

Un lote verifica una lista en segundo plano. Lo creas, esperas a que termine y descargas un resultado por fila.

## El flujo

1. `POST /batches` con una lista JSON o un fichero CSV. Responde `202` al instante con un lote en estado `queued`.
2. Espera: consulta `GET /batches/{batch_id}` o recibe el [webhook `batch.completed`](https://docs.salchimail.com/es/webhooks.md).
3. Descarga las filas de `GET /batches/{batch_id}/results`, en JSON o CSV.

**curl**

```bash
# 1. Create the batch. It answers 202 with the batch object.
curl https://api.salchimail.com/v1/batches \
  -H "Authorization: Bearer $SALCHIMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c1c0e-6d1f-4f0e-9f58-0d6b0a1c2e3f" \
  -d '{"emails": ["ana@example.com", "luis@example.org", "not-an-email"], "mode": "mailbox", "name": "November newsletter"}'

# 2. Check the status until it is "completed" (use the id from step 1).
curl https://api.salchimail.com/v1/batches/bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b \
  -H "Authorization: Bearer $SALCHIMAIL_API_KEY"

# 3. Read the results.
curl "https://api.salchimail.com/v1/batches/bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b/results?limit=1000" \
  -H "Authorization: Bearer $SALCHIMAIL_API_KEY"
```

**JavaScript / TypeScript**

```js
const API = "https://api.salchimail.com/v1";

async function api(path, init = {}) {
  const response = await fetch(API + path, {
    ...init,
    headers: { Authorization: `Bearer ${process.env.SALCHIMAIL_API_KEY}`, ...init.headers },
  });
  const body = await response.json();
  if (!response.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
  return body;
}

// 1. Create the batch. The Idempotency-Key makes a retry return the same batch.
let batch = await api("/batches", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({
    emails: ["ana@example.com", "luis@example.org", "not-an-email"],
    mode: "mailbox",
    name: "November newsletter",
  }),
});

// 2. Poll until it reaches a final status (or use the batch.completed webhook).
while (batch.status === "queued" || batch.status === "processing") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  batch = await api(`/batches/${batch.id}`);
}

// 3. Page through the results.
let cursor = null;
do {
  const query = new URLSearchParams({ limit: "1000", ...(cursor && { cursor }) });
  const page = await api(`/batches/${batch.id}/results?${query}`);
  for (const row of page.data) console.log(row.row, row.email, row.verdict);
  cursor = page.next_cursor;
} while (cursor);
```

**Python**

```python
import json
import os
import time
import urllib.error
import urllib.parse
import urllib.request
import uuid

API = "https://api.salchimail.com/v1"


def api(method, path, body=None, headers=None):
    request = urllib.request.Request(API + path, method=method, headers=headers or {})
    request.add_header("Authorization", f"Bearer {os.environ['SALCHIMAIL_API_KEY']}")
    if body is not None:
        request.data = json.dumps(body).encode()
        request.add_header("Content-Type", "application/json")
    try:
        with urllib.request.urlopen(request, timeout=30) as response:
            return json.load(response)
    except urllib.error.HTTPError as error:
        problem = json.load(error)["error"]
        raise SystemExit(f"{problem['code']}: {problem['message']}")


# 1. Create the batch. The Idempotency-Key makes a retry return the same batch.
batch = api(
    "POST",
    "/batches",
    {
        "emails": ["ana@example.com", "luis@example.org", "not-an-email"],
        "mode": "mailbox",
        "name": "November newsletter",
    },
    {"Idempotency-Key": str(uuid.uuid4())},
)

# 2. Poll until it reaches a final status (or use the batch.completed webhook).
while batch["status"] in ("queued", "processing"):
    time.sleep(5)
    batch = api("GET", f"/batches/{batch['id']}")

# 3. Page through the results.
query = {"limit": 1000}
while True:
    page = api("GET", f"/batches/{batch['id']}/results?{urllib.parse.urlencode(query)}")
    for row in page["data"]:
        print(row["row"], row["email"], row["verdict"])
    if not page["next_cursor"]:
        break
    query["cursor"] = page["next_cursor"]
```

**PHP**

```php
<?php
const API = "https://api.salchimail.com/v1";

function api(string $method, string $path, ?array $body = null, array $headers = []): array
{
    $headers[] = "Authorization: Bearer " . getenv("SALCHIMAIL_API_KEY");
    $ch = curl_init(API . $path);
    curl_setopt_array($ch, [CURLOPT_CUSTOMREQUEST => $method, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30]);
    if ($body !== null) {
        $headers[] = "Content-Type: application/json";
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    }
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    $raw = curl_exec($ch);
    if ($raw === false) {
        throw new RuntimeException(curl_error($ch));
    }
    $data = json_decode($raw, true);
    if (curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 400) {
        throw new RuntimeException("{$data['error']['code']}: {$data['error']['message']}");
    }
    return $data;
}

// 1. Create the batch. The Idempotency-Key makes a retry return the same batch.
$batch = api("POST", "/batches", [
    "emails" => ["ana@example.com", "luis@example.org", "not-an-email"],
    "mode" => "mailbox",
    "name" => "November newsletter",
], ["Idempotency-Key: " . bin2hex(random_bytes(16))]);

// 2. Poll until it reaches a final status (or use the batch.completed webhook).
while (in_array($batch["status"], ["queued", "processing"], true)) {
    sleep(5);
    $batch = api("GET", "/batches/{$batch['id']}");
}

// 3. Page through the results.
$query = ["limit" => 1000];
do {
    $page = api("GET", "/batches/{$batch['id']}/results?" . http_build_query($query));
    foreach ($page["data"] as $row) {
        echo "{$row['row']} {$row['email']} {$row['verdict']}\n";
    }
    $query["cursor"] = $page["next_cursor"];
} while ($page["next_cursor"]);
```

**Go**

```go
package main

import (
	"bytes"
	"crypto/rand"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"net/url"
	"os"
	"time"
)

const api = "https://api.salchimail.com/v1"

type batch struct {
	ID     string `json:"id"`
	Status string `json:"status"`
}

type resultPage struct {
	Data []struct {
		Row     int    `json:"row"`
		Email   string `json:"email"`
		Verdict string `json:"verdict"`
	} `json:"data"`
	NextCursor *string `json:"next_cursor"`
}

type apiError struct {
	Error struct {
		Code    string `json:"code"`
		Message string `json:"message"`
	} `json:"error"`
}

var client = &http.Client{Timeout: 30 * time.Second}

// call sends one request and decodes the JSON answer into out.
func call(method, path string, body any, idempotencyKey string, out any) error {
	var payload bytes.Buffer
	if body != nil {
		if err := json.NewEncoder(&payload).Encode(body); err != nil {
			return err
		}
	}
	req, err := http.NewRequest(method, api+path, &payload)
	if err != nil {
		return err
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SALCHIMAIL_API_KEY"))
	if body != nil {
		req.Header.Set("Content-Type", "application/json")
	}
	if idempotencyKey != "" {
		req.Header.Set("Idempotency-Key", idempotencyKey)
	}
	res, err := client.Do(req)
	if err != nil {
		return err
	}
	defer res.Body.Close()
	if res.StatusCode >= 400 {
		var e apiError
		if err := json.NewDecoder(res.Body).Decode(&e); err != nil {
			return fmt.Errorf("HTTP %d", res.StatusCode)
		}
		return fmt.Errorf("%s: %s", e.Error.Code, e.Error.Message)
	}
	return json.NewDecoder(res.Body).Decode(out)
}

func main() {
	// 1. Create the batch. The Idempotency-Key makes a retry return the same batch.
	var b batch
	request := map[string]any{
		"emails": []string{"ana@example.com", "luis@example.org", "not-an-email"},
		"mode":   "mailbox",
		"name":   "November newsletter",
	}
	if err := call("POST", "/batches", request, rand.Text(), &b); err != nil {
		log.Fatal(err)
	}

	// 2. Poll until it reaches a final status (or use the batch.completed webhook).
	for b.Status == "queued" || b.Status == "processing" {
		time.Sleep(5 * time.Second)
		if err := call("GET", "/batches/"+b.ID, nil, "", &b); err != nil {
			log.Fatal(err)
		}
	}

	// 3. Page through the results.
	query := url.Values{"limit": {"1000"}}
	for {
		var page resultPage
		if err := call("GET", "/batches/"+b.ID+"/results?"+query.Encode(), nil, "", &page); err != nil {
			log.Fatal(err)
		}
		for _, r := range page.Data {
			fmt.Println(r.Row, r.Email, r.Verdict)
		}
		if page.NextCursor == nil {
			break
		}
		query.Set("cursor", *page.NextCursor)
	}
}
```

## Crear un lote desde JSON

Envía hasta 10.000 direcciones en `emails`. `mode` es `basic` salvo que indiques otro, y `name` es una etiqueta opcional que se muestra en el panel.

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

La respuesta es el lote nuevo, anunciado también en la cabecera `Location`:

```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
}
```

## Crear un lote desde CSV

Sube el fichero como `multipart/form-data`:

```bash
curl https://api.salchimail.com/v1/batches \
  -H "Authorization: Bearer $SALCHIMAIL_API_KEY" \
  -H "Idempotency-Key: 6f1c1c0e-6d1f-4f0e-9f58-0d6b0a1c2e3f" \
  -F "file=@contacts.csv;type=text/csv" \
  -F "mode=mailbox" \
  -F "email_column=email" \
  -F "delimiter=comma" \
  -F "name=November newsletter"
```

| Campo | Obligatorio | Por defecto | Descripción |
| --- | --- | --- | --- |
| `file` | Sí | | CSV en UTF-8 con fila de cabecera. Hasta 10 MB y 100.000 filas de datos |
| `email_column` | No | `email` | Nombre exacto de la cabecera que contiene las direcciones |
| `delimiter` | No | `comma` | `comma`, `semicolon` o `tab` |
| `mode` | No | `basic` | `basic` o `mailbox` |
| `name` | No | | Etiqueta que se muestra en el panel, hasta 120 caracteres |

Solo se guarda la columna del email: el resto de columnas se descarta al subir el fichero. Cruza los resultados con tu fichero por `row`, el número de fila de datos sin contar la cabecera.

## Seguir el progreso

```bash
curl https://api.salchimail.com/v1/batches/bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b \
  -H "Authorization: Bearer $SALCHIMAIL_API_KEY"
```

```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
}
```

| Campo | Significado |
| --- | --- |
| `status` | `queued` → `processing` → `completed`. También `canceled`, y `failed` si hay un error interno |
| `total` | Filas aceptadas, duplicados incluidos |
| `unique` | Direcciones distintas tras normalizar |
| `processed` | Filas que ya tienen un resultado final |
| `summary` | Resultados finales hasta el momento, por veredicto |
| `credits` | `reserved` para las filas pendientes y `charged` hasta el momento |

Consulta como mucho cada pocos segundos. Para no tener que consultar, suscríbete al [webhook `batch.completed`](https://docs.salchimail.com/es/webhooks.md). `GET /batches` lista tus lotes, del más reciente al más antiguo.

## Descargar los resultados

Los resultados vienen ordenados por `row`. Cada uno es una [verificación](https://docs.salchimail.com/es/veredictos.md) con tres campos más: `row`, `input` (el valor tal como lo enviaste) y `duplicate`.

```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"
}
```

Las páginas traen 100 filas salvo que indiques `limit` (hasta 1.000 en JSON). Mientras `has_more` sea `true`, pide la página siguiente con `cursor=<next_cursor>`. Añade `verdict=valid` (o `invalid`, `risky`, `unknown`) para recibir solo esas filas.

### En CSV

```bash
curl "https://api.salchimail.com/v1/batches/bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b/results?format=csv&limit=10000" \
  -H "Authorization: Bearer $SALCHIMAIL_API_KEY" \
  -D headers.txt -o results.csv
```

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

Una página CSV trae hasta 10.000 filas. Cuando hay más, la respuesta incluye una cabecera `Link` con la página siguiente (`rel="next"`). En la última página la cabecera no aparece.

Solo se listan las filas con resultado final, así que las páginas pedidas mientras el lote está en `processing` son parciales. Espera a un estado final antes de hacer una exportación completa.

## Cuánto tarda un lote

| Fase | Plazo |
| --- | --- |
| Creación | `202` al instante. El lote empieza en `queued` |
| Lote `basic` | No se contacta con ningún servidor de correo |
| Lote `mailbox` | Respeta cuotas de sondeo por dominio y por servidor de correo, y reintenta las direcciones aplazadas. Una lista grande concentrada en pocos dominios puede tardar horas o días |
| Fecha límite | `deadline_at`, 6 días después de que empiece el lote. Las filas sin resolver terminan como `unknown` y **no se cobran** |
| Resultados disponibles | Hasta `results_expire_at`, 30 días después de terminar el lote. Después, el endpoint de resultados responde `404` |
| Modo de pruebas | Los lotes creados con una clave `sk_test_` terminan en segundos |

SalchiMail nunca rota direcciones IP ni esquiva los límites de un servidor de correo para ir más rápido, así que el ritmo de un lote `mailbox` depende de los servidores que hay detrás de tu lista.

## Créditos en un lote

- Al crear el lote se reservan créditos para cada dirección **única**. Si el saldo no llega, la petición responde `402 insufficient_credits` y no se crea nada.
- Cada fila se cobra cuando alcanza un resultado final, con las mismas reglas que una verificación individual. En modo `mailbox`, las filas `unknown` son gratis.
- Las direcciones duplicadas se verifican una vez y se cobran una vez. Las filas repetidas vuelven con `"duplicate": true`.
- Los créditos no usados se devuelven cuando el lote termina o se cancela.

Consulta [Créditos y facturación](https://docs.salchimail.com/es/creditos.md).

## Cancelar un lote

```bash
curl -X POST https://api.salchimail.com/v1/batches/bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b/cancel \
  -H "Authorization: Bearer $SALCHIMAIL_API_KEY"
```

Cancelar detiene un lote en `queued` o `processing`. Los resultados ya producidos siguen disponibles y cobrados, y los créditos reservados para el resto se devuelven. Las filas que no llegaron a procesarse no aparecen en los resultados. Un lote `completed` o `failed` responde `409 batch_not_cancelable`.

## Límites y errores

| Límite | Valor |
| --- | --- |
| Direcciones en un lote JSON | 10.000 |
| Cuerpo JSON | 2 MB |
| Fichero CSV | 10 MB y 100.000 filas de datos |
| Tu plan | `limits.max_batch_size` y `limits.max_concurrent_batches` en `GET /account` |

| HTTP | `code` | Significado |
| --- | --- | --- |
| 400 | `batch_empty` | La lista o el fichero no tienen direcciones |
| 400 | `batch_too_large` | Más filas de las que tu plan acepta en un lote |
| 400 | `csv_invalid` | El fichero no es un CSV legible en UTF-8 con fila de cabecera |
| 400 | `csv_column_not_found` | Ninguna cabecera coincide exactamente con `email_column` |
| 402 | `insufficient_credits` | No hay créditos suficientes para reservar el lote |
| 413 | `payload_too_large` | El cuerpo supera 2 MB (JSON) o 10 MB (CSV). Divide la lista |
| 429 | `concurrent_batches_exceeded` | Demasiados lotes en `queued` o `processing` a la vez. Espera a que termine uno |

Envía siempre una [`Idempotency-Key`](https://docs.salchimail.com/es/idempotencia.md) al crear un lote: así, un reintento tras un error de red devuelve el mismo lote en lugar de crear otro y reservar sus créditos.

Source: https://docs.salchimail.com/es/lotes

---

# Veredictos y reason codes

Toda verificación responde con un `verdict` y un `reason_code`. El veredicto es la decisión; el reason code es la evidencia que la sostiene.

## Los cuatro veredictos

| `verdict` | Significado | Qué hacer |
| --- | --- | --- |
| `valid` | El servidor de correo acepta al destinatario y rechaza una dirección de control aleatoria en el mismo servidor | Envía. No demuestra que alguien lea el buzón |
| `invalid` | Sintaxis no admitida, un dominio que no puede recibir correo o un «no existe ese destinatario» inequívoco | No envíes. Elimínala o pide una corrección |
| `risky` | Servidor que lo acepta todo, dominio desechable o heredado, reenvío, buzón lleno o desactivado, o un rechazo del proveedor sin confirmar | Decide según `reason_code` y según lo que te cueste un rebote |
| `unknown` | Buzón no comprobado (`basic`), tiempo agotado, greylisting, fallo temporal de DNS o SMTP, cuota de sondeo o respuesta ambigua | Consérvala. Reintenta después de `retry_at` cuando venga informado |

**Nunca trates `unknown` como `invalid`.** `unknown` significa «no hemos podido saberlo», no «no existe». En modo `mailbox`, un resultado `unknown` nunca se cobra.

Solo el modo `mailbox` puede devolver `valid`. El modo `basic` nunca contacta con el servidor de correo, así que un dominio sano da `unknown` con `mailbox_not_checked`.

## Reason codes

«Modo» indica dónde puede aparecer el código. Pueden añadirse códigos nuevos sin cambiar de versión: cuando encuentres uno que no conozcas, guíate por el `verdict`.

### `valid`

| `reason_code` | Modo | Significado | Qué hacer |
| --- | --- | --- | --- |
| `mailbox_exists` | mailbox | Destinatario aceptado y dirección de control aleatoria rechazada | Envía |

### `invalid`

| `reason_code` | Modo | Significado | Qué hacer |
| --- | --- | --- | --- |
| `syntax_invalid` | ambos | No es una dirección válida en el perfil ASCII admitido | Pide una corrección. No envíes nunca |
| `domain_not_found` | ambos | El dominio no existe (NXDOMAIN) | Suele ser una errata en el dominio. Pide una corrección |
| `domain_null_mx` | ambos | El dominio declara que no acepta correo (MX nulo, RFC 7505) | Elimínala |
| `domain_no_mail_host` | ambos | Sin registro MX y sin registro A ni AAAA | Elimínala |
| `mailbox_not_found` | mailbox | El servidor dice que el destinatario no existe | Elimínala. Un envío rebotaría |

### `risky`

| `reason_code` | Modo | Significado | Qué hacer |
| --- | --- | --- | --- |
| `disposable_domain` | ambos | El dominio está en la lista de emails desechables | Recházala en el registro o exclúyela de las campañas, según tu política |
| `legacy_domain` | ambos | Dominio de un proveedor que ya no existe | Pide una dirección actual. No cuentes con ella |
| `mailbox_disabled` | mailbox | El servidor dice que el buzón está desactivado | No envíes. Vuelve a comprobarla más adelante si el contacto importa |
| `mailbox_full` | mailbox | El servidor dice que el buzón está lleno | Un envío probablemente rebotaría. Vuelve a comprobarla más adelante |
| `mailbox_forwarded` | mailbox | El servidor anuncia un reenvío (SMTP 251) | Suele entregarse. El buzón final no se verifica |
| `provider_directory_rejected` | mailbox | Rechazo del directorio del proveedor (Microsoft 365) sin confirmar | Trátala como probablemente inexistente. Déjala fuera de los envíos masivos |
| `catch_all` | mailbox | El servidor también acepta a un destinatario aleatorio | El buzón no se puede confirmar. Envía solo si tienes otra señal, como actividad reciente |

### `unknown`

| `reason_code` | Modo | Significado | Qué hacer |
| --- | --- | --- | --- |
| `mailbox_not_checked` | basic | El dominio puede recibir correo y el buzón no se sondeó | Respuesta normal en `basic`. Usa el modo `mailbox` si necesitas certeza |
| `address_unsupported` | ambos | Dirección internacionalizada (no ASCII), no comprobada | No la rechaces. Verifícala por tus propios medios |
| `dns_temporary` | ambos | El DNS falló temporalmente. No se cobra | Reintenta más tarde |
| `catch_all_unresolved` | mailbox | Destinatario aceptado, pero el control de catch-all no fue concluyente | Reintenta más tarde. Hasta entonces, trátala como `catch_all` |
| `rejection_unconfirmed` | mailbox | Rechazada, pero una dirección de control que sabemos buena también lo fue | El rechazo no demuestra nada. Reintenta más tarde |
| `probe_rate_limited` | mailbox | Nuestra cuota horaria de sondeo para ese dominio o servidor está agotada | Reintenta después de `retry_at`. Los lotes lo hacen por ti |
| `probe_blocked` | mailbox | El servidor rechaza nuestro sondeo (reputación de IP, DNS inverso o política del remitente) | Reintentar no servirá a corto plazo. Trátala como no verificada |
| `smtp_temporary` | mailbox | Rechazo temporal o greylisting | Reintenta después de `retry_at`. Los lotes lo hacen por ti |
| `smtp_unreachable` | mailbox | No se pudo contactar con ningún servidor de correo | Reintenta más tarde |
| `smtp_tls_failed` | mailbox | No se pudo verificar la sesión TLS anunciada | Reintenta más tarde |
| `smtp_rejected` | mailbox | Rechazo ambiguo o por política que no demuestra que el buzón falte | Trátala como no verificada |

## El resto del resultado

```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"
}
```

| Campo | Qué te dice |
| --- | --- |
| `reason` | Explicación legible de `reason_code`, en inglés o español (`Accept-Language`) |
| `flags.disposable` | El dominio, o un dominio padre, está en la lista de desechables |
| `flags.free` | Proveedor de correo gratuito. Informativo: no cambia el veredicto |
| `flags.catch_all` | `true`: el servidor aceptó a un destinatario aleatorio. `false`: lo rechazó. `null`: no se probó o no fue concluyente |
| `checks` | Los pasos que se ejecutaron de verdad, en orden: `syntax`, listas de dominios, `dns`, `smtp`, `catch_all`. Los que no se ejecutaron no aparecen |
| `mx` | Servidores de correo del dominio. Vacío cuando no se resolvió el DNS |
| `smtp` | Lo que respondió el servidor a `RCPT TO`: `mx`, `code`, `enhanced_code`, `tls`. `null` en modo `basic` |
| `cached` | El resultado viene de una comprobación reciente. `checked_at` es la hora de esa comprobación |
| `credits_charged` | `0` o `1` crédito del tipo de `mode` |
| `retry_at` | Cuándo se puede volver a verificar un resultado temporal. `null` cuando reintentar no tiene sentido |

## Una política razonable de partida

| Situación | Enviar a `valid` | Enviar a `risky` | Enviar a `unknown` |
| --- | --- | --- | --- |
| Email transaccional que el usuario ha pedido | Sí | Sí | Sí |
| Boletín a personas que se suscribieron | Sí | Solo `mailbox_forwarded` y `catch_all` con actividad reciente | Tras un reintento, o en tandas pequeñas vigilando los rebotes |
| Lista fría o antigua | Sí | No | No, hasta que un reintento dé un veredicto |

Es un punto de partida, no una norma: tú sabes lo que te cuesta un rebote.

Source: https://docs.salchimail.com/es/veredictos

---

# Webhooks

SalchiMail puede llamar a tu servidor cuando ocurre algo, para que no tengas que consultar. Los endpoints se crean en el panel, en [app.salchimail.com](https://app.salchimail.com). Cada endpoint tiene una URL HTTPS y su propio secreto de firma.

## Eventos

| `type` | Cuándo se envía |
| --- | --- |
| `batch.completed` | Un lote llega a `completed` o `failed`. Comprueba `data.batch.status`. No se envía para los lotes que cancelas |
| `credits.low` | Un saldo de créditos cruza el umbral configurado en el panel (por defecto, el 10 % de la última concesión) |

Cada entrega es un `POST` con un evento en JSON:

```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"
    }
  }
}
```

`batch.completed` trae el lote, no sus filas: descárgalas con `GET /batches/{batch_id}/results` ([Limpieza de listas por lotes](https://docs.salchimail.com/es/lotes.md)).

```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
  }
}
```

`credits.low` se envía una vez cada vez que un saldo cruza el umbral. Solo vuelve a enviarse cuando el saldo se ha recargado por encima del umbral y cae otra vez por debajo.

## Verifica la firma

Cualquiera puede hacer un POST a tu URL, así que comprueba que cada entrega viene de SalchiMail antes de fiarte de ella. Toda entrega lleva esta cabecera:

```http
SalchiMail-Signature: t=1794909701,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
```

- `t` es la hora de la entrega, en segundos Unix.
- `v1` es `HMAC-SHA256(secreto_del_endpoint, "<t>.<cuerpo crudo de la petición>")`, en hexadecimal.

Para verificar una entrega:

1. Lee el **cuerpo crudo**, byte a byte, antes de interpretar el JSON. Volver a serializar el JSON cambia los bytes y rompe la firma.
2. Calcula el HMAC-SHA256 de `<t>.<cuerpo crudo>` con el secreto de tu endpoint.
3. Compáralo con `v1` usando una comparación en **tiempo constante**.
4. Rechaza la entrega cuando `t` tenga más de 5 minutos. Así evitas repeticiones maliciosas.
5. Mientras se rota un secreto, la cabecera puede traer varios valores `v1`. Acepta la entrega si alguno coincide.

Estos servidores verifican la firma y atienden los dos eventos. Leen el secreto de `SALCHIMAIL_WEBHOOK_SECRET`.

**JavaScript / TypeScript**

```js
import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";

function isValidSignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = (header ?? "").split(",").map((part) => part.split("="));
  const timestamp = parts.find(([key]) => key === "t")?.[1];
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!timestamp || !(age <= toleranceSeconds)) return false;

  const expected = createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest();
  // Several v1 values can be present while a secret is rotated: accept if any matches.
  return parts.some(([key, value]) => {
    const signature = Buffer.from((key === "v1" && value) || "", "hex");
    return signature.length === expected.length && timingSafeEqual(signature, expected);
  });
}

createServer(async (req, res) => {
  const chunks = [];
  for await (const chunk of req) chunks.push(chunk);
  const rawBody = Buffer.concat(chunks); // the raw bytes, before any JSON parsing

  if (!isValidSignature(rawBody, req.headers["salchimail-signature"], process.env.SALCHIMAIL_WEBHOOK_SECRET)) {
    res.writeHead(400).end();
    return;
  }
  const event = JSON.parse(rawBody);
  // Deduplicate by event.id, queue the work and answer within 10 seconds.
  if (event.type === "batch.completed") {
    console.log("batch finished:", event.data.batch.id, event.data.batch.status);
  } else if (event.type === "credits.low") {
    console.log("low credits:", event.data.credit_type, event.data.remaining);
  }
  res.writeHead(204).end();
}).listen(process.env.PORT ?? 3000);
```

**Python**

```python
import hashlib
import hmac
import json
import os
import time
from http.server import BaseHTTPRequestHandler, HTTPServer

SECRET = os.environ["SALCHIMAIL_WEBHOOK_SECRET"].encode()


def is_valid_signature(raw_body: bytes, header: str, secret: bytes, tolerance: int = 300) -> bool:
    parts = [part.split("=", 1) for part in header.split(",") if "=" in part]
    timestamp = next((value for key, value in parts if key == "t"), "")
    if not timestamp.isascii() or not timestamp.isdigit() or abs(time.time() - int(timestamp)) > tolerance:
        return False
    expected = hmac.new(secret, timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    # Several v1 values can be present while a secret is rotated: accept if any matches.
    return any(hmac.compare_digest(expected.encode(), value.encode()) for key, value in parts if key == "v1")


class Webhook(BaseHTTPRequestHandler):
    def do_POST(self):
        # The raw bytes, before any JSON parsing.
        raw_body = self.rfile.read(int(self.headers.get("Content-Length", 0)))
        if not is_valid_signature(raw_body, self.headers.get("SalchiMail-Signature", ""), SECRET):
            self.send_response(400)
            self.end_headers()
            return
        event = json.loads(raw_body)
        # Deduplicate by event["id"], queue the work and answer within 10 seconds.
        if event["type"] == "batch.completed":
            print("batch finished:", event["data"]["batch"]["id"], event["data"]["batch"]["status"], flush=True)
        elif event["type"] == "credits.low":
            print("low credits:", event["data"]["credit_type"], event["data"]["remaining"], flush=True)
        self.send_response(204)
        self.end_headers()


HTTPServer(("", int(os.environ.get("PORT", 3000))), Webhook).serve_forever()
```

**PHP**

```php
<?php
function is_valid_signature(string $rawBody, string $header, string $secret, int $tolerance = 300): bool
{
    $timestamp = "";
    $signatures = [];
    foreach (explode(",", $header) as $part) {
        [$key, $value] = array_pad(explode("=", $part, 2), 2, "");
        if ($key === "t") {
            $timestamp = $value;
        } elseif ($key === "v1") {
            $signatures[] = $value;
        }
    }
    if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > $tolerance) {
        return false;
    }
    $expected = hash_hmac("sha256", "$timestamp.$rawBody", $secret);
    // Several v1 values can be present while a secret is rotated: accept if any matches.
    foreach ($signatures as $signature) {
        if (hash_equals($expected, $signature)) {
            return true;
        }
    }
    return false;
}

$rawBody = file_get_contents("php://input"); // the raw bytes, before any JSON parsing
$header = $_SERVER["HTTP_SALCHIMAIL_SIGNATURE"] ?? "";
if (!is_valid_signature($rawBody, $header, getenv("SALCHIMAIL_WEBHOOK_SECRET"))) {
    http_response_code(400);
    exit;
}
$event = json_decode($rawBody, true);
// Deduplicate by $event["id"], queue the work and answer within 10 seconds.
if ($event["type"] === "batch.completed") {
    error_log("batch finished: {$event['data']['batch']['id']} {$event['data']['batch']['status']}");
} elseif ($event["type"] === "credits.low") {
    error_log("low credits: {$event['data']['credit_type']} {$event['data']['remaining']}");
}
http_response_code(204);
```

**Go**

```go
package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"io"
	"log"
	"net/http"
	"os"
	"strconv"
	"strings"
	"time"
)

func isValidSignature(rawBody []byte, header, secret string, tolerance time.Duration) bool {
	var timestamp string
	var signatures []string
	for _, part := range strings.Split(header, ",") {
		key, value, _ := strings.Cut(part, "=")
		switch key {
		case "t":
			timestamp = value
		case "v1":
			signatures = append(signatures, value)
		}
	}
	seconds, err := strconv.ParseInt(timestamp, 10, 64)
	if err != nil || time.Since(time.Unix(seconds, 0)).Abs() > tolerance {
		return false
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(timestamp + "."))
	mac.Write(rawBody)
	expected := mac.Sum(nil)
	// Several v1 values can be present while a secret is rotated: accept if any matches.
	for _, signature := range signatures {
		if got, err := hex.DecodeString(signature); err == nil && hmac.Equal(got, expected) {
			return true
		}
	}
	return false
}

type event struct {
	ID   string `json:"id"`
	Type string `json:"type"`
	Data struct {
		Batch struct {
			ID     string `json:"id"`
			Status string `json:"status"`
		} `json:"batch"`
		CreditType string `json:"credit_type"`
		Remaining  int    `json:"remaining"`
	} `json:"data"`
}

func main() {
	secret := os.Getenv("SALCHIMAIL_WEBHOOK_SECRET")

	http.HandleFunc("POST /webhooks/salchimail", func(w http.ResponseWriter, r *http.Request) {
		// The raw bytes, before any JSON parsing.
		rawBody, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 1<<20))
		if err != nil || !isValidSignature(rawBody, r.Header.Get("SalchiMail-Signature"), secret, 5*time.Minute) {
			w.WriteHeader(http.StatusBadRequest)
			return
		}
		var e event
		if err := json.Unmarshal(rawBody, &e); err != nil {
			w.WriteHeader(http.StatusBadRequest)
			return
		}
		// Deduplicate by e.ID, queue the work and answer within 10 seconds.
		switch e.Type {
		case "batch.completed":
			log.Println("batch finished:", e.Data.Batch.ID, e.Data.Batch.Status)
		case "credits.low":
			log.Println("low credits:", e.Data.CreditType, e.Data.Remaining)
		}
		w.WriteHeader(http.StatusNoContent)
	})

	port := os.Getenv("PORT")
	if port == "" {
		port = "3000"
	}
	log.Fatal(http.ListenAndServe(":"+port, nil))
}
```

En un framework, asegúrate de recibir el cuerpo crudo. Si antes se ejecuta un intérprete de JSON, te quedas sin los bytes que se firmaron.

## Responde rápido, trabaja después

- Responde con cualquier `2xx` en menos de **10 segundos**. Encola el trabajo lento y hazlo después de responder.
- Cualquier otra respuesta, o un tiempo de espera agotado, se reintenta con espera exponencial durante un máximo de 24 horas (8 intentos).
- Una entrega puede llegar **más de una vez** y **fuera de orden**. Deduplica por el `id` del evento, que es el mismo en todos los reintentos.
- Todos los eventos llevan `livemode`, como el resto de objetos de la API.

## Lista de comprobación

- La URL del endpoint usa HTTPS.
- La firma se verifica contra el cuerpo crudo con una comparación en tiempo constante.
- Las entregas con más de 5 minutos se rechazan.
- Los eventos se deduplican por `id`.
- El manejador responde `2xx` antes de hacer el trabajo lento.
- Los tipos de evento desconocidos se responden con `2xx` y se ignoran: pueden añadirse tipos nuevos.

Source: https://docs.salchimail.com/es/webhooks

---

# Idempotencia

Las redes fallan. Cuando a un `POST` se le agota el tiempo, no puedes saber si llegó a la API. Con una `Idempotency-Key` puedes enviarlo de nuevo sin verificar, crear ni cobrar dos veces.

## Cómo funciona

Añade la cabecera a cualquier `POST`: `/verify`, `/batches` y `/batches/{batch_id}/cancel`.

```bash
curl https://api.salchimail.com/v1/verify \
  -H "Authorization: Bearer $SALCHIMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c1c0e-6d1f-4f0e-9f58-0d6b0a1c2e3f" \
  -d '{"email": "ana@example.com", "mode": "mailbox"}'
```

- La clave es cualquier cadena única de hasta 255 caracteres. Un UUID es una buena opción.
- Las claves se guardan **24 horas**, por cuenta.
- Un reintento con la misma clave y el mismo cuerpo devuelve la respuesta guardada, con la cabecera `Idempotent-Replayed: true`, y **no cobra nada**.

## Conflictos

| HTTP | `code` | Significado | Qué hacer |
| --- | --- | --- | --- |
| 409 | `idempotency_key_reused` | La clave ya se usó con un cuerpo distinto | Usa una clave nueva para una petición nueva |
| 409 | `idempotency_in_progress` | La primera petición con esa clave sigue en curso | Espera y reintenta con la misma clave |

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

## Úsala bien

- Genera **una clave por operación**, no por intento: créala antes del primer intento y reutilízala en cada reintento.
- Guarda la clave junto al trabajo al que pertenece (el registro, la importación) para que un proceso reiniciado reintente con la misma clave.
- Reintenta ante errores de red, `429`, `500` y `503`, con la misma clave y una espera creciente. Consulta [Límites y errores](https://docs.salchimail.com/es/limites-y-errores.md).
- No reintentes `400`, `401`, `402`, `403` ni `404` sin cambiar algo: la respuesta será la misma.

La idempotencia importa sobre todo al [crear un lote](https://docs.salchimail.com/es/lotes.md): sin clave, un reintento tras un tiempo de espera agotado puede crear un segundo lote y reservar también sus créditos.

Las peticiones `GET` se pueden repetir sin riesgo y no necesitan clave.

Source: https://docs.salchimail.com/es/idempotencia

---

# Créditos y facturación

Una verificación cuesta un crédito, y solo cuando te aporta algo. Cada resultado dice lo que ha cobrado en `credits_charged`.

## Dos saldos

Cada `mode` tiene su propio saldo. Uno nunca paga por el otro.

| | Créditos `basic` | Créditos `mailbox` |
| --- | --- | --- |
| Los usa | `"mode": "basic"` | `"mode": "mailbox"` |
| De dónde salen | Asignación mensual de tu plan | Packs de pago único |
| Caducidad | Se renuevan en `resets_at`. No se acumulan | Consulta `next_expiry` en `GET /usage`. Primero se gastan los créditos que antes caducan |

| Plan | Créditos `basic` al mes |
| --- | --- |
| Gratis | 1.000 |
| Básico | 20.000 |
| Básico+ | 150.000 |

Una cuenta nueva empieza con 100 créditos de buzón. Los packs de buzón son de 2.500, 10.000, 50.000 y 100.000 verificaciones. Los precios vigentes están en la [página de precios](https://salchimail.com/es/#precios) y las condiciones de los packs, en los [términos](https://salchimail.com/es/terminos). Planes y packs se compran en el panel, en [app.salchimail.com](https://app.salchimail.com), donde también están tus facturas.

## Qué se cobra

| Modo | Se cobra | Gratis |
| --- | --- | --- |
| `basic` | 1 crédito basic por verificación terminada, sea cual sea el veredicto | Los resultados `dns_temporary`. Las repeticiones de la misma dirección en 30 días |
| `mailbox` | 1 crédito mailbox **solo cuando el veredicto no es `unknown`** | Todos los `unknown`. Las repeticiones de la misma dirección en 24 horas. Los duplicados dentro de un lote |

También es gratis, siempre:

- Las peticiones que terminan en error (`4xx`, `5xx`), incluido `503 verification_timeout`.
- Las repeticiones de una petición con la misma [`Idempotency-Key`](https://docs.salchimail.com/es/idempotencia.md).
- Todo lo que se hace con una clave `sk_test_` ([Entorno de pruebas](https://docs.salchimail.com/es/entorno-de-pruebas.md)).

## Créditos en los lotes

Un lote **reserva** un crédito por dirección única al crearse, cobra cada fila cuando alcanza un resultado final y devuelve lo que sobra al terminar o al cancelarse. Los créditos reservados no están disponibles para otras peticiones mientras el lote está en curso. Detalles en [Limpieza de listas por lotes](https://docs.salchimail.com/es/lotes.md).

## Consulta tu saldo

```bash
curl https://api.salchimail.com/v1/usage \
  -H "Authorization: Bearer $SALCHIMAIL_API_KEY"
```

```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
    }
  }
}
```

| Campo | Significado |
| --- | --- |
| `credits.*.remaining` | Lo que puedes gastar ahora |
| `credits.*.reserved` | Retenido por lotes en curso |
| `credits.basic.granted` | Asignación mensual del periodo actual |
| `credits.basic.resets_at` | Cuándo se renueva la asignación basic |
| `credits.mailbox.next_expiry` | Los próximos créditos mailbox que caducan (`amount` y `at`), o `null` cuando ninguno caduca |
| `period` | Periodo de facturación actual de la asignación basic |
| `usage` | Verificaciones terminadas y créditos cobrados en el periodo, por modo |

## Cuando se acaban los créditos

Sin créditos del tipo que necesita una petición, la API responde `402`:

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

Un `402` no bloquea el otro modo: sin créditos mailbox, las verificaciones `basic` siguen funcionando.

Para enterarte antes de que ocurra, suscríbete al [webhook `credits.low`](https://docs.salchimail.com/es/webhooks.md). Se dispara cuando un saldo cruza el umbral configurado en el panel (por defecto, el 10 % de la última concesión).

Source: https://docs.salchimail.com/es/creditos

---

# Límites y errores

## Límites de peticiones

Los límites dependen de tu plan. `GET /account` devuelve en `limits` los que se aplican a tu clave.

| Plan | Peticiones por minuto | Filas por lote | Lotes simultáneos |
| --- | --- | --- | --- |
| Gratis | 60 | 100 | 1 |
| Básico | 600 | 100.000 | 3 |
| Básico+ | 1.200 | 100.000 | 5 |

Estos son los valores actuales. La fuente de verdad es `GET /account`.

Todas las respuestas llevan tres cabeceras:

| Cabecera | Significado |
| --- | --- |
| `RateLimit-Limit` | Peticiones permitidas en la ventana actual |
| `RateLimit-Remaining` | Peticiones que quedan en la ventana actual |
| `RateLimit-Reset` | Segundos hasta que se reinicia la ventana |

Por encima del límite, la API responde `429` con una cabecera `Retry-After`, en segundos. Espera ese tiempo y reintenta.

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

## Límites de tamaño

| Qué | Límite |
| --- | --- |
| `email` | 1.024 caracteres |
| Direcciones en un lote JSON | 10.000 |
| Cuerpo JSON | 2 MB |
| Fichero CSV | 10 MB y 100.000 filas de datos |
| `name` de un lote | 120 caracteres |
| `Idempotency-Key` | 255 caracteres |
| Página de lotes (`limit`) | 100, por defecto 20 |
| Página de resultados (`limit`) | 1.000 en JSON, 10.000 en CSV, por defecto 100 |
| Una verificación `mailbox` | 30 segundos; después, `503 verification_timeout` |

## El formato de error

Todos los errores tienen la misma forma:

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

| Campo | Significado |
| --- | --- |
| `type` | La clase general del error |
| `code` | Estable y pensado para máquinas. Decide según este campo |
| `message` | Para personas. No lo analices. En inglés por defecto; en español con `Accept-Language: es` |
| `param` | El campo de la petición al que se refiere el error, cuando lo hay |
| `request_id` | El mismo valor que la cabecera de respuesta `X-Request-Id`. Cítalo cuando escribas a soporte |

Pueden añadirse valores nuevos de `code` sin cambiar de versión. Trata un código que no conozcas según su `type`.

## Códigos de error

| HTTP | `type` | `code` | Significado | Qué hacer |
| --- | --- | --- | --- | --- |
| 400 | `invalid_request` | `invalid_json` | El cuerpo no es JSON válido | Corrige la petición |
| 400 | `invalid_request` | `missing_parameter` | Falta un campo obligatorio (mira `param`) | Corrige la petición |
| 400 | `invalid_request` | `invalid_parameter` | Un campo o parámetro tiene un valor no admitido (mira `param`) | Corrige la petición |
| 400 | `invalid_request` | `batch_empty` | El lote no tiene direcciones | Envía al menos una |
| 400 | `invalid_request` | `batch_too_large` | Más filas de las que tu plan acepta en un lote | Divide la lista |
| 400 | `invalid_request` | `csv_invalid` | El fichero no es un CSV legible en UTF-8 con fila de cabecera | Corrige el fichero |
| 400 | `invalid_request` | `csv_column_not_found` | Ninguna cabecera coincide con `email_column` | Envía el nombre exacto de la cabecera |
| 401 | `authentication` | `missing_api_key` | Falta la cabecera `Authorization: Bearer` | Envía tu clave |
| 401 | `authentication` | `invalid_api_key` | La clave no existe | Revisa la clave |
| 401 | `authentication` | `revoked_api_key` | La clave se revocó | Usa una clave vigente |
| 402 | `payment_required` | `insufficient_credits` | No hay créditos suficientes del tipo que necesita la petición | Recarga. Consulta [Créditos y facturación](https://docs.salchimail.com/es/creditos.md) |
| 403 | `permission` | `mode_not_allowed` | La cuenta no puede usar ese `mode` | Consulta `limits.modes` en `GET /account` |
| 403 | `permission` | `account_suspended` | La cuenta está suspendida | Escribe a soporte |
| 404 | `not_found` | `not_found` | El recurso no existe, es de otra cuenta o ha caducado | Revisa el identificador |
| 409 | `conflict` | `idempotency_key_reused` | Misma `Idempotency-Key`, cuerpo distinto | Usa una clave nueva |
| 409 | `conflict` | `idempotency_in_progress` | La primera petición con esa clave sigue en curso | Espera y reintenta |
| 409 | `conflict` | `batch_not_cancelable` | El lote ya está `completed` o `failed` | No hay nada que cancelar |
| 413 | `invalid_request` | `payload_too_large` | El cuerpo supera 2 MB (JSON) o 10 MB (CSV) | Divide la lista |
| 415 | `invalid_request` | `unsupported_media_type` | `Content-Type` incorrecto | Usa `application/json`, o `multipart/form-data` para lotes CSV |
| 429 | `rate_limit` | `rate_limit_exceeded` | Demasiadas peticiones | Espera los segundos de `Retry-After` |
| 429 | `rate_limit` | `concurrent_batches_exceeded` | Demasiados lotes en curso a la vez | Espera a que termine uno |
| 500 | `api_error` | `internal_error` | Error inesperado por nuestra parte | Reintenta con la misma `Idempotency-Key` |
| 503 | `api_error` | `engine_unavailable` | El motor de verificación no está disponible. No se cobró nada | Reintenta más tarde |
| 503 | `api_error` | `verification_timeout` | La comprobación no terminó a tiempo. No se cobró nada | Reintenta más tarde o usa un lote |

## Qué reintentar

| Respuesta | ¿Reintentar? |
| --- | --- |
| Error de red o tiempo de espera agotado | Sí, con la misma [`Idempotency-Key`](https://docs.salchimail.com/es/idempotencia.md) |
| `429` | Sí, después de `Retry-After` |
| `500`, `503` | Sí, con una espera creciente entre intentos |
| `409 idempotency_in_progress` | Sí, tras una espera corta |
| `400`, `401`, `402`, `403`, `404`, `413`, `415` | No. La respuesta no cambiará hasta que cambie la petición o la cuenta |

Duplica la espera tras cada intento fallido y para después de unos pocos. Un error nunca cobra créditos.

Una verificación que responde `200` con veredicto `unknown` no es un error: consulta [Veredictos y reason codes](https://docs.salchimail.com/es/veredictos.md).

Source: https://docs.salchimail.com/es/limites-y-errores

---

# Uso desde agentes de IA

Esta documentación está escrita para que la lean personas y máquinas. Todo lo que necesita un agente está disponible como texto plano.

## Documentación legible por máquinas

| Recurso | URL | Para qué sirve |
| --- | --- | --- |
| `llms.txt` | [`/es/llms.txt`](https://docs.salchimail.com/es/llms.txt) | Un índice de la documentación con una línea por página |
| `llms-full.txt` | [`/es/llms-full.txt`](https://docs.salchimail.com/es/llms-full.txt) | Todas las guías y la referencia de la API en un solo fichero |
| Páginas en Markdown | Añade `.md` a la URL de cualquier página, por ejemplo [`/es/inicio-rapido.md`](https://docs.salchimail.com/es/inicio-rapido.md) | Leer una página sin HTML |
| Referencia de la API en Markdown | [`/reference.md`](https://docs.salchimail.com/reference.md) (en inglés) | Todas las operaciones, esquemas y ejemplos |
| OpenAPI 3.1 | [`/openapi.json`](https://docs.salchimail.com/openapi.json) · [`/openapi.yaml`](https://docs.salchimail.com/openapi.yaml) | Generar clientes y definiciones de herramientas |

Todos se sirven con `Access-Control-Allow-Origin: *`.

## Servidor MCP

**Próximamente.** Un servidor MCP remoto en `mcp.salchimail.com` permitirá a un agente verificar direcciones, lanzar lotes y consultar el uso con tu clave de API. Esta página lo enlazará cuando esté disponible.

## Skill para agentes

**Próximamente.** Una skill que enseña a un asistente de programación a integrar SalchiMail. Esta página la enlazará cuando esté disponible.

Hasta que existan, apunta tu agente a [`/es/llms.txt`](https://docs.salchimail.com/es/llms.txt) o al contrato OpenAPI: basta para llamar a la API correctamente.

## Reglas para tu agente

Si escribes tú las instrucciones, incluye estas:

- La clave de API es un secreto. Léela de una variable de entorno, envíala solo a `https://api.salchimail.com` y no la imprimas nunca.
- Construye y prueba con una clave `sk_test_`: los resultados son simulados y no se consumen créditos ([Entorno de pruebas](https://docs.salchimail.com/es/entorno-de-pruebas.md)).
- Nunca trates `unknown` como `invalid` ([Veredictos y reason codes](https://docs.salchimail.com/es/veredictos.md)).
- Para más de unas pocas direcciones, crea un lote en lugar de repetir `POST /verify` ([Limpieza de listas por lotes](https://docs.salchimail.com/es/lotes.md)).
- Envía una `Idempotency-Key` en cada `POST` y reutilízala en los reintentos ([Idempotencia](https://docs.salchimail.com/es/idempotencia.md)).
- Decide según `verdict`, `reason_code` y el `code` del error. Nunca analices `reason` ni `message`.
- Una verificación nunca envía un email. No digas a los usuarios que se ha enviado un mensaje a la dirección.

Source: https://docs.salchimail.com/es/agentes-ia

---

# Changelog

## Cómo se versiona la API

La versión forma parte de la URL: `https://api.salchimail.com/v1`.

Dentro de `v1`, los cambios son **aditivos**. Estos pueden ocurrir sin cambiar de versión, así que escribe tu integración para tolerarlos:

- Endpoints nuevos, campos opcionales nuevos en las peticiones y campos nuevos en las respuestas.
- Valores nuevos de `reason_code` y del `code` de error. Trata un valor que no conozcas según su `verdict` o su `type` de error.
- Tipos nuevos de evento de webhook.

Eliminar o renombrar un campo, cambiar su tipo o cambiar el significado de un veredicto sería un cambio incompatible y se publicaría como una versión nueva.

## 2026-11-17 · API v1.0.0

Primera versión del contrato de la API pública.

- `POST /verify`: verifica una dirección en modo `basic` o `mailbox`.
- `POST /batches`, `GET /batches`, `GET /batches/{batch_id}`, `GET /batches/{batch_id}/results` y `POST /batches/{batch_id}/cancel`: verifica listas desde JSON o CSV y descarga los resultados en JSON o CSV.
- `GET /usage` y `GET /account`: créditos, uso, plan y límites.
- Webhooks `batch.completed` y `credits.low`, firmados con HMAC-SHA256.
- `Idempotency-Key` en todos los `POST`, modo de pruebas con claves `sk_test_` y un único formato de error para toda la API.

Source: https://docs.salchimail.com/es/changelog

---

# 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"`

