# SalchiMail Docs

> SalchiMail is an email verification API that never sends email: mailbox checks stop at `RCPT TO`. Verify one address per request or clean lists in batches. Every result has a verdict (`valid`, `invalid`, `risky`, `unknown`) and a stable `reason_code`.

- Base URL: `https://api.salchimail.com/v1`. JSON over HTTPS.
- Authentication: `Authorization: Bearer sk_live_…` (or `sk_test_…` for test mode). Keys are server-side secrets.
- Two modes: `basic` (syntax, domain lists, DNS) and `mailbox` (adds the SMTP `RCPT TO` probe). Each has its own credit balance.
- Never treat `unknown` as `invalid`.

---

# Quickstart

From zero to your first verified address in under five minutes. You need a SalchiMail account and a terminal.

## 1. Create an API key

Sign in to the dashboard at [app.salchimail.com](https://app.salchimail.com) and create an API key. The key is shown **once**: copy it now.

- `sk_live_…` keys run real verifications and use credits.
- `sk_test_…` keys return simulated results and never use credits. See [Test mode](https://docs.salchimail.com/test-mode.md).

Keep the key in an environment variable. It is a secret: use it from your server, never from a browser or a mobile app.

```bash
export SALCHIMAIL_API_KEY="sk_live_your_key"
```

## 2. Verify an address

Replace `ana@example.com` with an address you know and run the request. `mode` is `mailbox` here, so the mail server is asked whether the mailbox exists. No email is sent.

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

A mailbox check talks to the recipient's mail server and can take up to 30 seconds, so give your HTTP client a timeout above that.

## 3. Read the result

The answer is a verification object:

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

Start with `verdict`, then read `reason_code` for the why:

| `verdict` | What it means | What to do |
| --- | --- | --- |
| `valid` | The server accepts this recipient and rejects a random one | Send |
| `invalid` | Bad syntax, a domain that cannot receive mail, or a clear "no such recipient" | Do not send |
| `risky` | Accept-all server, disposable domain, full or disabled mailbox, and similar | Decide by `reason_code` |
| `unknown` | The check could not finish or was not done | **Do not treat it as `invalid`**. Retry after `retry_at` when present |

`credits_charged` tells you what this call cost. In `mailbox` mode an `unknown` result is free. The full list is in [Verdicts and reason codes](https://docs.salchimail.com/verdicts.md).

## 4. Pick the mode for your case

- **A sign-up form**: use `"mode": "basic"`. It checks syntax, domain lists and DNS in well under a second. See [Verify at sign-up](https://docs.salchimail.com/signup-verification.md).
- **A list**: send it as a batch instead of one request per address. See [Clean a list in batches](https://docs.salchimail.com/batches.md).

## Next steps

- [Authentication](https://docs.salchimail.com/authentication.md): key types, rotation and what a `401` means.
- [Idempotency](https://docs.salchimail.com/idempotency.md): retry a `POST` safely.
- [Limits and errors](https://docs.salchimail.com/limits-and-errors.md): rate limits and every error code.
- [API reference](https://docs.salchimail.com/reference.md): every endpoint, field and example.

Source: https://docs.salchimail.com/quickstart

---

# Authentication

Every request carries a secret API key in the `Authorization` header:

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

## Keys

Keys are created in the dashboard at [app.salchimail.com](https://app.salchimail.com). A key is shown once, when you create it, and SalchiMail stores only a hash of it. If you lose a key, create a new one.

| Prefix | Mode | Behaviour |
| --- | --- | --- |
| `sk_live_` | Live | Real verifications. Uses credits |
| `sk_test_` | Test | Simulated results, no credits. See [Test mode](https://docs.salchimail.com/test-mode.md) |

A key belongs to your organisation, not to a person. Create one key per application or environment and give each a name you will recognise later.

## Keep keys on the server

A key is a secret with access to your credits.

- Call the API from your backend. Never ship a key in a web page, a mobile app or a public repository.
- The API does not send CORS headers, so a request made from a browser will fail by design.
- Load the key from an environment variable or a secret manager, not from source code.

## Check which key you are using

`GET /account` returns the organisation, the plan, the limits and the key behind the request. The secret is never returned, only its `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` is `false` when the request used a `sk_test_` key.

## Rotate a key

1. Create a new key in the dashboard.
2. Deploy it to your application.
3. Revoke the old key. From that moment it answers `401 revoked_api_key`.

## Authentication errors

A request without a usable key answers `401` with the header `WWW-Authenticate: Bearer`:

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

| HTTP | `code` | Meaning | What to do |
| --- | --- | --- | --- |
| 401 | `missing_api_key` | No `Authorization: Bearer` header | Send the header on every request |
| 401 | `invalid_api_key` | The key does not exist | Check for a truncated or mistyped key |
| 401 | `revoked_api_key` | The key was revoked in the dashboard | Use a current key |
| 403 | `mode_not_allowed` | The account may not use that `mode` | Check `limits.modes` in `GET /account` |
| 403 | `account_suspended` | The account is suspended | Write to [hola@salchimail.com](mailto:hola@salchimail.com) |

The shape of every error is described in [Limits and errors](https://docs.salchimail.com/limits-and-errors.md).

Source: https://docs.salchimail.com/authentication

---

# Test mode

A key that starts with `sk_test_` runs in test mode: **no real verification is performed and no credits are used**. Use it to build your integration and in automated tests.

## Predictable verdicts

Syntax is still checked. After that, the verdict is chosen by the local part of the address (the text before `@`):

| Address | `verdict` | `reason_code` |
| --- | --- | --- |
| `valid@…` | `valid` | |
| `invalid@…` | `invalid` | |
| `risky@…` | `risky` | `catch_all` |
| `disposable@…` | `risky` | `disposable_domain` |
| Anything else | `unknown` | |

The contract fixes the `reason_code` only for the two `risky` cases. Assert on `verdict` in the others.

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

## What is different from live mode

- Objects carry `"livemode": false`, including `GET /account` and `GET /usage`.
- No credits are charged or reserved.
- Test batches complete within seconds, so you can exercise the whole [batch flow](https://docs.salchimail.com/batches.md): create, poll, download.
- The mail server of the address is never contacted.

Everything else is the same contract: the same endpoints, fields, [errors](https://docs.salchimail.com/limits-and-errors.md) and [idempotency](https://docs.salchimail.com/idempotency.md) rules.

## Suggested use

- Keep a `sk_test_` key in your development and CI environments, and the `sk_live_` key only in production.
- Cover each branch of your code with the matching address: one test with `valid@`, one with `invalid@`, one with `risky@` and one with an address that gives `unknown`.
- Check `livemode` in your tests to make sure they never run against live credits.

Source: https://docs.salchimail.com/test-mode

---

# Verify at sign-up

Stop typos, dead domains and disposable addresses at the form, without making real users wait.

## The recommended pattern

1. The form posts to **your server**. The API key never reaches the browser.
2. Your server calls `POST /verify` with `"mode": "basic"` and a short timeout.
3. Reject `invalid`, apply your policy to disposable domains and accept the rest.
4. If the call fails or times out, **accept the sign-up** and verify later.
5. Send your confirmation email as usual.

**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"));
```

## Timings

| Mode | Typical answer | Suggested client timeout | Where to run it |
| --- | --- | --- | --- |
| `basic` | Well under a second | 3 seconds | Inline, while the form is submitted |
| `mailbox` | Up to 30 seconds | Above 30 seconds | In a background job, after the sign-up |

`basic` never contacts the mail server, which is why it is fast. `mailbox` talks to the recipient's server: if it cannot finish in 30 seconds the API answers `503 verification_timeout` and charges nothing. Do not hold a sign-up form open for a mailbox check.

If you want mailbox certainty for new users, run a `mailbox` verification from a background job once the account exists, and act on the result before your first campaign.

## What to do with each result

| Result in `basic` mode | Meaning | Suggested action |
| --- | --- | --- |
| `invalid` · `syntax_invalid` | Not an email address | Ask the user to correct it |
| `invalid` · `domain_not_found`, `domain_null_mx`, `domain_no_mail_host` | The domain cannot receive mail. Often a typo | Ask the user to check the domain |
| `risky` · `disposable_domain` | Throwaway address | Reject or ask for another address, by your policy |
| `risky` · `legacy_domain` | Domain of a discontinued provider | Ask for another address |
| `unknown` · `mailbox_not_checked` | The domain can receive mail. This is the normal answer | Accept |
| `unknown` · `dns_temporary`, `address_unsupported` | The check could not be done | Accept |

`flags.free` tells you the domain is a free webmail provider. It is informational and does not change the verdict.

To show a message to the user, map `reason_code` to your own copy. `reason` is a ready-made explanation in English or, with the header `Accept-Language: es`, in Spanish.

## Rules that keep sign-ups safe

- **Fail open.** A timeout, a `429`, a `402` or a `5xx` must never cost you a real user. Accept and verify later.
- **Never treat `unknown` as `invalid`.** In `basic` mode `unknown` is the answer for every healthy domain.
- **Keep your confirmation email.** `valid` says the server accepts the address. It does not prove the person owns it or reads it.
- **Re-submits are cheap.** Verifying the same address again within 30 days in `basic` mode is free, so a user who submits the form twice is charged once.
- **Retries are safe** with an [`Idempotency-Key`](https://docs.salchimail.com/idempotency.md).

See [Verdicts and reason codes](https://docs.salchimail.com/verdicts.md) for the complete list and [Limits and errors](https://docs.salchimail.com/limits-and-errors.md) for rate limits.

Source: https://docs.salchimail.com/signup-verification

---

# Clean a list in batches

A batch verifies a list in the background. You create it, wait for it to finish and download one result per row.

## The flow

1. `POST /batches` with a JSON list or a CSV file. It answers `202` at once with a batch in status `queued`.
2. Wait: poll `GET /batches/{batch_id}` or receive the [`batch.completed` webhook](https://docs.salchimail.com/webhooks.md).
3. Download the rows from `GET /batches/{batch_id}/results`, as JSON or 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)
	}
}
```

## Create a batch from JSON

Send up to 10,000 addresses in `emails`. `mode` is `basic` unless you say otherwise, and `name` is an optional label shown in the dashboard.

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

The answer is the new batch, also announced in the `Location` header:

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

## Create a batch from CSV

Upload the file as `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"
```

| Field | Required | Default | Description |
| --- | --- | --- | --- |
| `file` | Yes | | UTF-8 CSV with a header row. Up to 10 MB and 100,000 data rows |
| `email_column` | No | `email` | Exact name of the header that holds the addresses |
| `delimiter` | No | `comma` | `comma`, `semicolon` or `tab` |
| `mode` | No | `basic` | `basic` or `mailbox` |
| `name` | No | | Label shown in the dashboard, up to 120 characters |

Only the email column is stored: every other column is discarded on upload. Join the results back to your file by `row`, the data row number with the header excluded.

## Follow progress

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

| Field | Meaning |
| --- | --- |
| `status` | `queued` → `processing` → `completed`. Also `canceled`, and `failed` for an internal error |
| `total` | Rows accepted, duplicates included |
| `unique` | Distinct addresses after normalisation |
| `processed` | Rows that already have a final result |
| `summary` | Final results so far, by verdict |
| `credits` | `reserved` for rows still pending and `charged` so far |

Poll every few seconds at most. To avoid polling, subscribe to the [`batch.completed` webhook](https://docs.salchimail.com/webhooks.md). `GET /batches` lists your batches, newest first.

## Download the results

Results are ordered by `row`. Each one is a [verification](https://docs.salchimail.com/verdicts.md) plus three fields: `row`, `input` (the value exactly as you sent it) and `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"
}
```

Pages hold 100 rows unless you set `limit` (up to 1,000 for JSON). While `has_more` is `true`, request the next page with `cursor=<next_cursor>`. Add `verdict=valid` (or `invalid`, `risky`, `unknown`) to get only those rows.

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

A CSV page holds up to 10,000 rows. When there are more, the response carries a `Link` header with the next page (`rel="next"`). The header is absent on the last page.

Only rows with a final result are listed, so pages requested while the batch is `processing` are partial. Wait for a final status before a complete export.

## How long a batch takes

| Stage | Timing |
| --- | --- |
| Creation | `202` at once. The batch starts `queued` |
| `basic` batch | No mail server is contacted |
| `mailbox` batch | Respects probe quotas per domain and per mail server, and retries deferred addresses. A large list concentrated on a few domains can take hours or days |
| Deadline | `deadline_at`, 6 days after the batch starts. Rows still unresolved end as `unknown` and are **not charged** |
| Results available | Until `results_expire_at`, 30 days after the batch finishes. After that the results endpoint answers `404` |
| Test mode | Batches created with a `sk_test_` key complete within seconds |

SalchiMail never rotates IP addresses or works around a mail server's limits to go faster, so the pace of a `mailbox` batch depends on the servers behind your list.

## Credits in a batch

- Credits for every **unique** address are reserved when the batch is created. If the balance is too low the request answers `402 insufficient_credits` and nothing is created.
- Each row is charged when it reaches a final result, by the same rules as a single verification. In `mailbox` mode `unknown` rows are free.
- Duplicated addresses are verified once and charged once. The repeated rows come back with `"duplicate": true`.
- Unused credits are returned when the batch finishes or is canceled.

See [Credits and billing](https://docs.salchimail.com/credits.md).

## Cancel a batch

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

Canceling stops a `queued` or `processing` batch. Results already produced stay available and charged, and the credits reserved for the rest are returned. Rows that were never processed are omitted from the results. A `completed` or `failed` batch answers `409 batch_not_cancelable`.

## Limits and errors

| Limit | Value |
| --- | --- |
| Addresses in a JSON batch | 10,000 |
| JSON body | 2 MB |
| CSV file | 10 MB and 100,000 data rows |
| Your plan | `limits.max_batch_size` and `limits.max_concurrent_batches` in `GET /account` |

| HTTP | `code` | Meaning |
| --- | --- | --- |
| 400 | `batch_empty` | The list or the file has no addresses |
| 400 | `batch_too_large` | More rows than your plan accepts in one batch |
| 400 | `csv_invalid` | The file is not a readable UTF-8 CSV with a header row |
| 400 | `csv_column_not_found` | No header matches `email_column` exactly |
| 402 | `insufficient_credits` | Not enough credits to reserve the batch |
| 413 | `payload_too_large` | The body is over 2 MB (JSON) or 10 MB (CSV). Split the list |
| 429 | `concurrent_batches_exceeded` | Too many batches `queued` or `processing` at once. Wait for one to finish |

Always send an [`Idempotency-Key`](https://docs.salchimail.com/idempotency.md) when you create a batch: a retry after a network error then returns the same batch instead of creating, and reserving credits for, a second one.

Source: https://docs.salchimail.com/batches

---

# Verdicts and reason codes

Every verification answers with a `verdict` and a `reason_code`. The verdict is the decision; the reason code is the evidence behind it.

## The four verdicts

| `verdict` | Meaning | What to do |
| --- | --- | --- |
| `valid` | The mail server accepts the recipient and rejects a random control address on the same server | Send. It does not prove the mailbox is read |
| `invalid` | Unsupported syntax, a domain that cannot receive mail, or an unambiguous "no such recipient" | Do not send. Remove it or ask for a correction |
| `risky` | Accept-all server, disposable or legacy domain, forwarding, full or disabled mailbox, or a provider rejection without confirmation | Decide by `reason_code` and by how much a bounce costs you |
| `unknown` | Mailbox not checked (`basic`), timeout, greylisting, temporary DNS or SMTP failure, probe quota or an ambiguous answer | Keep it. Retry after `retry_at` when present |

**Never treat `unknown` as `invalid`.** `unknown` means "we could not tell", not "it does not exist". In `mailbox` mode an `unknown` result is never charged.

Only `mailbox` mode can return `valid`. `basic` mode never contacts the mail server, so a healthy domain gives `unknown` with `mailbox_not_checked`.

## Reason codes

"Mode" says where the code can appear. New codes may be added without a version change: when you meet one you do not know, fall back on the `verdict`.

### `valid`

| `reason_code` | Mode | Meaning | What to do |
| --- | --- | --- | --- |
| `mailbox_exists` | mailbox | Recipient accepted and a random control address rejected | Send |

### `invalid`

| `reason_code` | Mode | Meaning | What to do |
| --- | --- | --- | --- |
| `syntax_invalid` | both | Not a valid address in the supported ASCII profile | Ask for a correction. Never send |
| `domain_not_found` | both | The domain does not exist (NXDOMAIN) | Usually a typo in the domain. Ask for a correction |
| `domain_null_mx` | both | The domain declares that it accepts no mail (null MX, RFC 7505) | Remove |
| `domain_no_mail_host` | both | No MX record and no A or AAAA record | Remove |
| `mailbox_not_found` | mailbox | The server says the recipient does not exist | Remove. Sending would bounce |

### `risky`

| `reason_code` | Mode | Meaning | What to do |
| --- | --- | --- | --- |
| `disposable_domain` | both | The domain is on the disposable-email list | Reject at sign-up or exclude from campaigns, by your policy |
| `legacy_domain` | both | Domain of a discontinued provider | Ask for a current address. Do not rely on it |
| `mailbox_disabled` | mailbox | The server says the mailbox is disabled | Suppress. Check again later if the contact matters |
| `mailbox_full` | mailbox | The server says the mailbox is full | A send would probably bounce. Check again later |
| `mailbox_forwarded` | mailbox | The server announces forwarding (SMTP 251) | Usually deliverable. The final mailbox is not verified |
| `provider_directory_rejected` | mailbox | Provider directory rejection (Microsoft 365) without confirmation | Treat as probably missing. Keep it out of bulk sends |
| `catch_all` | mailbox | The server also accepts a random recipient | The mailbox cannot be confirmed. Send only if you have another signal, such as recent activity |

### `unknown`

| `reason_code` | Mode | Meaning | What to do |
| --- | --- | --- | --- |
| `mailbox_not_checked` | basic | The domain can receive mail and the mailbox was not probed | Normal answer in `basic`. Use `mailbox` mode if you need certainty |
| `address_unsupported` | both | Internationalised (non-ASCII) address, not checked | Do not reject it. Verify it by your own means |
| `dns_temporary` | both | DNS failed temporarily. Not charged | Retry later |
| `catch_all_unresolved` | mailbox | Recipient accepted, but the catch-all control was inconclusive | Retry later. Until then treat it like `catch_all` |
| `rejection_unconfirmed` | mailbox | Rejected, but a known-good control address was rejected too | The rejection proves nothing. Retry later |
| `probe_rate_limited` | mailbox | Our hourly probe quota for that domain or server is exhausted | Retry after `retry_at`. Batches do it for you |
| `probe_blocked` | mailbox | The server refuses our probe (IP reputation, reverse DNS or sender policy) | A retry will not help soon. Treat as unverified |
| `smtp_temporary` | mailbox | Temporary rejection or greylisting | Retry after `retry_at`. Batches do it for you |
| `smtp_unreachable` | mailbox | No mail server could be reached | Retry later |
| `smtp_tls_failed` | mailbox | The advertised TLS session could not be verified | Retry later |
| `smtp_rejected` | mailbox | Ambiguous or policy rejection that does not prove the mailbox is missing | Treat as unverified |

## The rest of the result

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

| Field | What it tells you |
| --- | --- |
| `reason` | Human-readable explanation of `reason_code`, in English or Spanish (`Accept-Language`) |
| `flags.disposable` | The domain, or a parent domain, is on the disposable list |
| `flags.free` | Free webmail provider. Informational: it does not change the verdict |
| `flags.catch_all` | `true`: the server accepted a random recipient. `false`: it rejected it. `null`: not tested or inconclusive |
| `checks` | The steps that actually ran, in order: `syntax`, domain lists, `dns`, `smtp`, `catch_all`. Steps that did not run are absent |
| `mx` | Mail servers of the domain. Empty when DNS was not resolved |
| `smtp` | What the server answered to `RCPT TO`: `mx`, `code`, `enhanced_code`, `tls`. `null` in `basic` mode |
| `cached` | The result comes from a recent check. `checked_at` is the time of that check |
| `credits_charged` | `0` or `1` credit of the type of `mode` |
| `retry_at` | When a temporary result can be verified again. `null` when a retry makes no sense |

## A sensible default policy

| Situation | Send to `valid` | Send to `risky` | Send to `unknown` |
| --- | --- | --- | --- |
| Transactional email the user asked for | Yes | Yes | Yes |
| Newsletter to people who signed up | Yes | Only `mailbox_forwarded` and `catch_all` with recent activity | After a retry, or in small batches while you watch bounces |
| Cold or old list | Yes | No | No, until a retry gives a verdict |

This is a starting point, not a rule: you know what a bounce costs you.

Source: https://docs.salchimail.com/verdicts

---

# Webhooks

SalchiMail can call your server when something happens, so you do not have to poll. Endpoints are created in the dashboard at [app.salchimail.com](https://app.salchimail.com). Each endpoint has an HTTPS URL and its own signing secret.

## Events

| `type` | Sent when |
| --- | --- |
| `batch.completed` | A batch reaches `completed` or `failed`. Check `data.batch.status`. Not sent for batches you cancel |
| `credits.low` | A credit balance crosses the threshold set in the dashboard (default: 10% of the last grant) |

Each delivery is a `POST` with a JSON event:

```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` carries the batch, not its rows: fetch them with `GET /batches/{batch_id}/results` ([Clean a list in batches](https://docs.salchimail.com/batches.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` is sent once each time a balance crosses the threshold. It is sent again only after the balance has been topped up above the threshold and falls below it again.

## Verify the signature

Anyone can post to your URL, so check that each delivery comes from SalchiMail before you trust it. Every delivery carries this header:

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

- `t` is the time of the delivery, in Unix seconds.
- `v1` is `HMAC-SHA256(endpoint_secret, "<t>.<raw request body>")`, in hexadecimal.

To verify a delivery:

1. Read the **raw body**, byte for byte, before any JSON parsing. Re-serialising the JSON changes the bytes and breaks the signature.
2. Compute the HMAC-SHA256 of `<t>.<raw body>` with your endpoint secret.
3. Compare it with `v1` using a **constant-time** comparison.
4. Reject the delivery when `t` is more than 5 minutes old. This stops replays.
5. While a secret is being rotated the header can carry several `v1` values. Accept the delivery if any of them matches.

These servers verify the signature and handle both events. They read the secret from `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))
}
```

In a framework, make sure you get the raw body. A JSON body parser that runs first leaves you without the bytes that were signed.

## Answer fast, work later

- Answer with any `2xx` within **10 seconds**. Queue slow work and do it after you answer.
- Any other answer, or a timeout, is retried with exponential backoff for up to 24 hours (8 attempts).
- A delivery can arrive **more than once** and **out of order**. Deduplicate by the event `id`, which is the same across retries.
- Every event carries `livemode`, like the rest of the API objects.

## Checklist

- The endpoint URL uses HTTPS.
- The signature is verified against the raw body with a constant-time comparison.
- Deliveries older than 5 minutes are rejected.
- Events are deduplicated by `id`.
- The handler answers `2xx` before doing slow work.
- Unknown event types are answered with `2xx` and ignored: new types may be added.

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

---

# Idempotency

Networks fail. When a `POST` times out you cannot know whether it reached the API. With an `Idempotency-Key` you can send it again without verifying, creating or charging twice.

## How it works

Add the header to any `POST`: `/verify`, `/batches` and `/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"}'
```

- The key is any unique string of up to 255 characters. A UUID is a good choice.
- Keys are kept **24 hours**, per account.
- A retry with the same key and the same body returns the stored response, with the header `Idempotent-Replayed: true`, and **charges nothing**.

## Conflicts

| HTTP | `code` | Meaning | What to do |
| --- | --- | --- | --- |
| 409 | `idempotency_key_reused` | The key was already used with a different body | Use a new key for a new request |
| 409 | `idempotency_in_progress` | The first request with that key is still running | Wait and retry with the same key |

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

## Use it well

- Generate **one key per operation**, not per attempt: create it before the first try and reuse it on every retry.
- Store the key next to the job it belongs to (the sign-up, the import) so that a restarted process retries with the same key.
- Retry on network errors, `429`, `500` and `503`, with the same key and an increasing wait. See [Limits and errors](https://docs.salchimail.com/limits-and-errors.md).
- Do not retry `400`, `401`, `402`, `403` or `404` without changing something: the answer will be the same.

Idempotency matters most when you [create a batch](https://docs.salchimail.com/batches.md): without a key, a retry after a timeout can create a second batch and reserve its credits too.

`GET` requests are safe to repeat and need no key.

Source: https://docs.salchimail.com/idempotency

---

# Credits and billing

One verification costs one credit, and only when it gives you something. Every result says what it charged in `credits_charged`.

## Two balances

Each `mode` has its own balance. One never pays for the other.

| | `basic` credits | `mailbox` credits |
| --- | --- | --- |
| Used by | `"mode": "basic"` | `"mode": "mailbox"` |
| Where they come from | Monthly allowance of your plan | One-off packs |
| Expiry | Reset at `resets_at`. They do not roll over | See `next_expiry` in `GET /usage`. Credits closest to expiring are spent first |

| Plan | `basic` credits per month |
| --- | --- |
| Free | 1,000 |
| Basic | 20,000 |
| Basic+ | 150,000 |

A new account starts with 100 mailbox credits. Mailbox packs come in 2,500, 10,000, 50,000 and 100,000 verifications. Current prices are on the [pricing page](https://salchimail.com/#pricing), and the conditions that apply to packs are in the [terms](https://salchimail.com/terms). Plans and packs are bought in the dashboard at [app.salchimail.com](https://app.salchimail.com), where you also find your invoices.

## What is charged

| Mode | Charged | Free |
| --- | --- | --- |
| `basic` | 1 basic credit per completed verification, whatever the verdict | `dns_temporary` results. Repeats of the same address within 30 days |
| `mailbox` | 1 mailbox credit **only when the verdict is not `unknown`** | Every `unknown`. Repeats of the same address within 24 hours. Duplicates inside a batch |

Also free, always:

- Requests that end in an error (`4xx`, `5xx`), including `503 verification_timeout`.
- Replays of a request with the same [`Idempotency-Key`](https://docs.salchimail.com/idempotency.md).
- Everything done with a `sk_test_` key ([Test mode](https://docs.salchimail.com/test-mode.md)).

## Credits in batches

A batch **reserves** one credit per unique address when it is created, charges each row as it reaches a final result, and returns what is left when it finishes or is canceled. Reserved credits are not available to other requests while the batch runs. Details in [Clean a list in batches](https://docs.salchimail.com/batches.md).

## Check your balance

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

| Field | Meaning |
| --- | --- |
| `credits.*.remaining` | What you can spend now |
| `credits.*.reserved` | Held by running batches |
| `credits.basic.granted` | Monthly allowance of the current period |
| `credits.basic.resets_at` | When the basic allowance resets |
| `credits.mailbox.next_expiry` | The next mailbox credits to expire (`amount` and `at`), or `null` when none expire |
| `period` | Current billing period of the basic allowance |
| `usage` | Verifications completed and credits charged in the period, by mode |

## When credits run out

With no credits of the type a request needs, the API answers `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"
  }
}
```

A `402` does not block the other mode: with no mailbox credits left, `basic` verifications keep working.

To hear about it before it happens, subscribe to the [`credits.low` webhook](https://docs.salchimail.com/webhooks.md). It fires when a balance crosses the threshold set in the dashboard (default: 10% of the last grant).

Source: https://docs.salchimail.com/credits

---

# Limits and errors

## Rate limits

Limits depend on your plan. `GET /account` returns the ones that apply to your key in `limits`.

| Plan | Requests per minute | Rows per batch | Batches at once |
| --- | --- | --- | --- |
| Free | 60 | 100 | 1 |
| Basic | 600 | 100,000 | 3 |
| Basic+ | 1,200 | 100,000 | 5 |

These are the current values. `GET /account` is the source of truth.

Every response carries three headers:

| Header | Meaning |
| --- | --- |
| `RateLimit-Limit` | Requests allowed in the current window |
| `RateLimit-Remaining` | Requests left in the current window |
| `RateLimit-Reset` | Seconds until the window resets |

Over the limit the API answers `429` with a `Retry-After` header, in seconds. Wait that long and retry.

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

## Size limits

| What | Limit |
| --- | --- |
| `email` | 1,024 characters |
| Addresses in a JSON batch | 10,000 |
| JSON body | 2 MB |
| CSV file | 10 MB and 100,000 data rows |
| Batch `name` | 120 characters |
| `Idempotency-Key` | 255 characters |
| Page of batches (`limit`) | 100, default 20 |
| Page of results (`limit`) | 1,000 as JSON, 10,000 as CSV, default 100 |
| A `mailbox` verification | 30 seconds, then `503 verification_timeout` |

## The error format

Every error has the same shape:

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

| Field | Meaning |
| --- | --- |
| `type` | The broad class of the error |
| `code` | Stable and machine-readable. Branch on this |
| `message` | For humans. Do not parse it. English by default, Spanish with `Accept-Language: es` |
| `param` | The request field the error refers to, when there is one |
| `request_id` | Same value as the `X-Request-Id` response header. Quote it when you write to support |

New `code` values may be added without a version change. Treat a code you do not know as its `type`.

## Error codes

| HTTP | `type` | `code` | Meaning | What to do |
| --- | --- | --- | --- | --- |
| 400 | `invalid_request` | `invalid_json` | The body is not valid JSON | Fix the request |
| 400 | `invalid_request` | `missing_parameter` | A required field is missing (see `param`) | Fix the request |
| 400 | `invalid_request` | `invalid_parameter` | A field or query parameter has a value that is not accepted (see `param`) | Fix the request |
| 400 | `invalid_request` | `batch_empty` | The batch has no addresses | Send at least one |
| 400 | `invalid_request` | `batch_too_large` | More rows than your plan accepts in one batch | Split the list |
| 400 | `invalid_request` | `csv_invalid` | The file is not a readable UTF-8 CSV with a header row | Fix the file |
| 400 | `invalid_request` | `csv_column_not_found` | No header matches `email_column` | Send the exact header name |
| 401 | `authentication` | `missing_api_key` | No `Authorization: Bearer` header | Send your key |
| 401 | `authentication` | `invalid_api_key` | The key does not exist | Check the key |
| 401 | `authentication` | `revoked_api_key` | The key was revoked | Use a current key |
| 402 | `payment_required` | `insufficient_credits` | Not enough credits of the type the request needs | Top up. See [Credits and billing](https://docs.salchimail.com/credits.md) |
| 403 | `permission` | `mode_not_allowed` | The account may not use that `mode` | Check `limits.modes` in `GET /account` |
| 403 | `permission` | `account_suspended` | The account is suspended | Write to support |
| 404 | `not_found` | `not_found` | The resource does not exist, belongs to another account or has expired | Check the identifier |
| 409 | `conflict` | `idempotency_key_reused` | Same `Idempotency-Key`, different body | Use a new key |
| 409 | `conflict` | `idempotency_in_progress` | The first request with that key is still running | Wait and retry |
| 409 | `conflict` | `batch_not_cancelable` | The batch is already `completed` or `failed` | Nothing to cancel |
| 413 | `invalid_request` | `payload_too_large` | The body is over 2 MB (JSON) or 10 MB (CSV) | Split the list |
| 415 | `invalid_request` | `unsupported_media_type` | Wrong `Content-Type` | Use `application/json`, or `multipart/form-data` for CSV batches |
| 429 | `rate_limit` | `rate_limit_exceeded` | Too many requests | Wait `Retry-After` seconds |
| 429 | `rate_limit` | `concurrent_batches_exceeded` | Too many batches running at once | Wait for one to finish |
| 500 | `api_error` | `internal_error` | Unexpected error on our side | Retry with the same `Idempotency-Key` |
| 503 | `api_error` | `engine_unavailable` | The verification engine is unavailable. Nothing was charged | Retry later |
| 503 | `api_error` | `verification_timeout` | The check did not finish in time. Nothing was charged | Retry later, or use a batch |

## What to retry

| Answer | Retry? |
| --- | --- |
| Network error or timeout | Yes, with the same [`Idempotency-Key`](https://docs.salchimail.com/idempotency.md) |
| `429` | Yes, after `Retry-After` |
| `500`, `503` | Yes, with an increasing wait between attempts |
| `409 idempotency_in_progress` | Yes, after a short wait |
| `400`, `401`, `402`, `403`, `404`, `413`, `415` | No. The answer will not change until the request or the account changes |

Double the wait after each failed attempt and stop after a few. An error never charges credits.

A verification that answers `200` with verdict `unknown` is not an error: see [Verdicts and reason codes](https://docs.salchimail.com/verdicts.md).

Source: https://docs.salchimail.com/limits-and-errors

---

# Use from AI agents

These docs are written to be read by people and by machines. Everything an agent needs is available as plain text.

## Machine-readable docs

| Resource | URL | Use it for |
| --- | --- | --- |
| `llms.txt` | [`/llms.txt`](https://docs.salchimail.com/llms.txt) | An index of the docs with one line per page |
| `llms-full.txt` | [`/llms-full.txt`](https://docs.salchimail.com/llms-full.txt) | Every guide and the API reference in a single file |
| Markdown pages | Add `.md` to any page URL, for example [`/quickstart.md`](https://docs.salchimail.com/quickstart.md) | Reading one page without HTML |
| API reference in Markdown | [`/reference.md`](https://docs.salchimail.com/reference.md) | Every operation, schema and example |
| OpenAPI 3.1 | [`/openapi.json`](https://docs.salchimail.com/openapi.json) · [`/openapi.yaml`](https://docs.salchimail.com/openapi.yaml) | Generating clients and tool definitions |

All of them are served with `Access-Control-Allow-Origin: *`.

## MCP server

**Coming soon.** A remote MCP server at `mcp.salchimail.com` will let an agent verify addresses, run batches and read usage with your API key. This page will link to it when it is available.

## Agent skill

**Coming soon.** A skill that teaches a coding assistant how to integrate SalchiMail. This page will link to it when it is available.

Until both exist, point your agent at [`/llms.txt`](https://docs.salchimail.com/llms.txt) or at the OpenAPI contract: it is enough to call the API correctly.

## Rules to give your agent

If you write the instructions yourself, include these:

- The API key is a secret. Read it from an environment variable, send it only to `https://api.salchimail.com` and never print it.
- Build and test with a `sk_test_` key: results are simulated and no credits are used ([Test mode](https://docs.salchimail.com/test-mode.md)).
- Never treat `unknown` as `invalid` ([Verdicts and reason codes](https://docs.salchimail.com/verdicts.md)).
- For more than a few addresses, create a batch instead of looping over `POST /verify` ([Clean a list in batches](https://docs.salchimail.com/batches.md)).
- Send an `Idempotency-Key` on every `POST`, and reuse it on retries ([Idempotency](https://docs.salchimail.com/idempotency.md)).
- Branch on `verdict`, `reason_code` and the error `code`. Never parse `reason` or `message`.
- A verification never sends email. Do not tell users that a message was sent to the address.

Source: https://docs.salchimail.com/ai-agents

---

# Changelog

## How the API is versioned

The version is part of the URL: `https://api.salchimail.com/v1`.

Inside `v1`, changes are **additive**. These can happen without a version change, so write your integration to tolerate them:

- New endpoints, new optional request fields and new fields in responses.
- New values of `reason_code` and of the error `code`. Treat a value you do not know as its `verdict` or its error `type`.
- New webhook event types.

Removing or renaming a field, changing its type or changing the meaning of a verdict would be a breaking change and would ship as a new version.

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

First version of the public API contract.

- `POST /verify`: verify one address in `basic` or `mailbox` mode.
- `POST /batches`, `GET /batches`, `GET /batches/{batch_id}`, `GET /batches/{batch_id}/results` and `POST /batches/{batch_id}/cancel`: verify lists from JSON or CSV and download the results as JSON or CSV.
- `GET /usage` and `GET /account`: credits, usage, plan and limits.
- Webhooks `batch.completed` and `credits.low`, signed with HMAC-SHA256.
- `Idempotency-Key` on every `POST`, test mode with `sk_test_` keys and one error format for the whole API.

Source: https://docs.salchimail.com/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"`

