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
POST /batcheswith a JSON list or a CSV file. It answers202at once with a batch in statusqueued.- Wait: poll
GET /batches/{batch_id}or receive thebatch.completedwebhook. - Download the rows from
GET /batches/{batch_id}/results, as JSON or CSV.
# 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"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);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
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"]);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.
{
"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:
{
"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:
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
curl https://api.salchimail.com/v1/batches/bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b \
-H "Authorization: Bearer $SALCHIMAIL_API_KEY"{
"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. GET /batches lists your batches, newest first.
Download the results
Results are ordered by row. Each one is a verification plus three fields: row, input (the value exactly as you sent it) and duplicate.
{
"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
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.csvrow,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:02ZA 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_creditsand nothing is created. - Each row is charged when it reaches a final result, by the same rules as a single verification. In
mailboxmodeunknownrows 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.
Cancel a batch
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 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.