# 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.
