Skip to main content
POST
/
api
/
v1
/
email-verification
/
batch
Batch Verify
curl --request POST \
  --url https://api.example.com/api/v1/email-verification/batch \
  --header 'Content-Type: application/json' \
  --data '
{
  "emails": [
    "<string>"
  ]
}
'
{
  "verificationId": "<string>",
  "totalEmails": 123,
  "creditsDeducted": 123,
  "status": "<string>",
  "results": [
    {}
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.mailbreeze.com/llms.txt

Use this file to discover all available pages before exploring further.

Submit a batch of email addresses for verification. For large batches, results are processed asynchronously - use the verification ID to poll for results.

​
Request Body

​
emails
string[]
required
Array of email addresses to verify. Maximum 1000 emails per batch.

​
Examples

import { MailBreeze } from "mailbreeze";

const mailbreeze = new MailBreeze({ apiKey: "sk_live_xxx" });

// Submit batch for verification
const batch = await mailbreeze.verification.batch({
  emails: [
    "user1@example.com",
    "user2@example.com",
    "user3@example.com",
  ],
});

console.log(`Batch ID: ${batch.verificationId}`);
console.log(`Status: ${batch.status}`);
console.log(`Credits deducted: ${batch.creditsDeducted}`);

// If all emails were cached, results are immediate
if (batch.results) {
  console.log("All results from cache:");
  for (const result of batch.results) {
    console.log(`${result.email}: ${result.result}`);
  }
} else {
  // Poll for results
  let status = await mailbreeze.verification.get(batch.verificationId);

  while (status.status === "processing") {
    await new Promise(r => setTimeout(r, 2000)); // Wait 2 seconds
    status = await mailbreeze.verification.get(batch.verificationId);
    console.log(`Progress: ${status.processedEmails}/${status.totalEmails}`);
  }

  console.log("Results:", status.results);
  console.log("Analytics:", status.analytics);
}

​
Response

​
verificationId
string
Unique ID for polling batch status.
​
totalEmails
integer
Total number of emails in the batch.
​
creditsDeducted
integer
Number of credits deducted (cached emails are free).
​
status
string
Current batch status:
  • pending - Batch submitted, not yet started
  • processing - Verification in progress
  • completed - All emails verified
  • failed - Batch verification failed
​
results
array
Only populated when all emails were cached. Contains array of verification results.
Example Response
{
  "success": true,
  "data": {
    "totalEmails": 2,
    "creditsDeducted": 4,
    "status": "completed",
    "analytics": {
      "cleanCount": 0,
      "dirtyCount": 2,
      "unknownCount": 0,
      "cleanPercentage": 0
    },
    "results": {
      "clean": [],
      "dirty": [
        "test1@example.com",
        "test2@example.com"
      ],
      "unknown": []
    }
  },
  "meta": {
    "timestamp": "2025-12-27T13:39:38.819Z",
    "requestId": "5e1686a9-05dd-4693-bc5d-fd596fb16bdf",
    "path": "/api/v1/email-verification/batch"
  }
}
The response is wrapped in an envelope with success, data, and meta fields. SDKs automatically extract the data object.

​
Limits

LimitValue
Max emails per batch1,000
Max concurrent batches5
Processing time~1-2 seconds per email

​
Credits

  • New emails: 1 credit per email
  • Cached emails: 0 credits (cached 24 hours)
  • Credits are deducted upfront when batch is submitted

​
Errors

CodeHTTP StatusDescription
BATCH_TOO_LARGE400More than 1000 emails in batch
INSUFFICIENT_CREDITS402Not enough credits for batch
TOO_MANY_BATCHES429Too many concurrent batches
VALIDATION_ERROR400Invalid email format in batch