Skip to content
SimpleCold

API docs

Endpoints

Verify a batch of addresses

On this page

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.

POST/api/v1/api-validation/batch

Request body

JSON, with Content-Type: application/json.

FieldTypeRequiredDescription
emailsstring[]YesThe addresses to verify. Up to 50 per request. Every item must be a valid email address.

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]"]}'
Response · 200
{
  "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

  • 50 addresses per request.
  • 10 requests per minute per API key.
  • Set your client timeout above 25 seconds.

Errors

HTTPBodyCause
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

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]","[email protected]"]}'

Test addresses return fixed results and don't use credits. See Test emails.

Batch validation | SimpleCold API docs