Verify a batch of addresses
Checks up to 50 addresses in one request and returns one result per address, in the same shape as a single check. Use it for small lists from a script.
/api/v1/api-validation/batchRequest body
JSON, with Content-Type: application/json.
| Field | Type | Required | Description |
|---|---|---|---|
emails | string[] | Yes | The addresses to verify. Up to 50 per request. Every item must be a valid email address. |
{
"emails": ["[email protected]", "[email protected]", "[email protected]"]
}Request
curl -X POST "https://simplecold.com/api/v1/api-validation/batch" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"emails":["[email protected]","[email protected]","[email protected]"]}'const API = "https://simplecold.com/api/v1";
const apiKey = process.env.SIMPLECOLD_API_KEY;
async function verifyBatch(emails) {
const res = await fetch(`${API}/api-validation/batch`, {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ emails }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${body.message ?? body.error}`);
return body.payload;
}
const results = await verifyBatch(["[email protected]", "[email protected]"]);
for (const r of results) console.log(r.email, r.category, r.status);
// Collect any still-running checks later with /single/result
const pending = results.filter((r) => r.status === "processing").map((r) => r.email);import os
import requests
API = "https://simplecold.com/api/v1"
API_KEY = os.environ["SIMPLECOLD_API_KEY"]
res = requests.post(
f"{API}/api-validation/batch",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"emails": ["[email protected]", "[email protected]"]},
timeout=60,
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code}: {body.get('message') or body.get('error')}")
for r in body["payload"]:
print(r["email"], r["category"], r["status"])
pending = [r["email"] for r in body["payload"] if r["status"] == "processing"]<?php
const API = 'https://simplecold.com/api/v1';
$ch = curl_init(API . '/api-validation/batch');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('SIMPLECOLD_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['emails' => ['[email protected]', '[email protected]']]),
CURLOPT_TIMEOUT => 60,
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($status >= 400) {
throw new RuntimeException($status . ': ' . ($body['message'] ?? $body['error'] ?? 'request failed'));
}
foreach ($body['payload'] as $r) {
echo $r['email'], ' ', $r['category'], ' ', $r['status'], PHP_EOL;
}
$pending = array_column(array_filter($body['payload'], fn ($r) => $r['status'] === 'processing'), 'email');{
"code": "SUCCESS",
"message": "Successfully performed operation.",
"payload": [
{
"email": "[email protected]",
"domain": "example.com",
"status": "mailbox_found",
"statusMessage": "The mailbox exists and accepts mail.",
"category": "deliverable",
"failType": "none",
"mxLocation": "US",
"siteLocation": "US",
"siteLanguage": "EN",
"suggestion": null
},
{
"email": "[email protected]",
"domain": "example.org",
"status": "role_address",
"statusMessage": "This is a shared role address, like info@ or sales@, not a person.",
"category": "risky",
"failType": "none",
"mxLocation": "US",
"siteLocation": "US",
"siteLanguage": "EN",
"suggestion": null
},
{
"email": "[email protected]",
"domain": "gmial.com",
"status": "possible_typo",
"statusMessage": "Possible typo. Did you mean [email protected]?",
"category": "undeliverable",
"failType": "permanent",
"mxLocation": null,
"siteLocation": null,
"siteLanguage": null,
"suggestion": "[email protected]"
}
],
"requestId": "4c2e7a90-..."
}payload is an array with one result per address, in the same order as your emails. The email field is trimmed and lowercased, so match by position, or compare lowercased addresses.
Response fields
Each item has the same fields as a single result: email, domain, category, status, statusMessage, failType, mxLocation, siteLocation, siteLanguage and suggestion. The reason codes are listed in Statuses and categories.
Slow mail servers
A batch request answers within about 25 seconds. Addresses whose mail servers have not answered by then come back with "status": "processing" and "category": "pending", while the rest of the batch contains final results. Those checks keep running on our side.
Treat each item on its own. Don't resend the whole batch because one item is pending. Collect the pending ones with GET /api-validation/single/result?email=... (see Slow mail servers), or include them in a new batch within 30 minutes. Neither uses extra credits: each address is charged once, when its final result is ready.
Limits
Errors
| HTTP | Body | Cause |
|---|---|---|
400 | { "code": "FAILURE", "message": "Maximum 50 emails per request is allowed.", "data": null } | More than 50 addresses. Split into chunks of 50. |
400 | { "success": false, "message": "Please check your input and try again.", "data": [...] } | emails is missing, or an item is not a valid email address. data[].path points at the item, for example ["emails", 2]. |
400 | { "code": "FAILURE", "message": "Insufficient credits.", "data": null } | Your balance can't cover the batch (Please buy credits. when it is empty). |
401 | { "code": "FAILURE", "message": "Invalid API key", "data": null } | See authentication errors. |
429 | { "code": "RATE_LIMITED", "message": "Rate limit exceeded. Maximum 10 requests per minute per API key.", "data": { "policy": "...", "retryAfterSeconds": 6, ... }, "status": 429, "error": "..." } | Over 10 batch requests per minute with this API key. Wait Retry-After seconds. See Rate limits. |
Larger lists
For more than 50 addresses, either send several batches of up to 50 (paced to stay within 10 requests per minute), or upload the list as a CSV with bulk validation.
Test it
curl -X POST "https://simplecold.com/api/v1/api-validation/batch" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"emails":["[email protected]","[email protected]","[email protected]","[email protected]"]}'Test addresses return fixed results and don't use credits. See Test emails.