Skip to main content
GET
/
api
/
v1
/
email-verification
/
{id}
Get Verification
curl --request GET \
  --url https://api.example.com/api/v1/email-verification/{id}
{
  "id": "<string>",
  "status": "<string>",
  "totalEmails": 123,
  "processedEmails": 123,
  "creditsDeducted": 123,
  "createdAt": "<string>",
  "completedAt": "<string>",
  "results": [
    {}
  ],
  "analytics": {
    "valid": 123,
    "invalid": 123,
    "risky": 123,
    "unknown": 123
  }
}

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.

Retrieve the status and results of a batch verification. Poll this endpoint until status is completed or failed.

​
Path Parameters

​
id
string
required
The verification batch ID (e.g., ver_abc123).

​
Examples

import { MailBreeze } from "mailbreeze";

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

const status = await mailbreeze.verification.get("ver_abc123");

console.log(`Status: ${status.status}`);
console.log(`Progress: ${status.processedEmails}/${status.totalEmails}`);

if (status.status === "completed") {
  console.log(`Completed at: ${status.completedAt}`);

  // View analytics summary
  console.log("Analytics:", status.analytics);
  // { valid: 85, invalid: 10, risky: 3, unknown: 2 }

  // Access individual results
  for (const result of status.results) {
    console.log(`${result.email}: ${result.result} (${result.isValid ? "✓" : "✗"})`);
  }
}

​
Response

​
id
string
Verification batch ID.
​
status
string
Current status:
  • pending - Not yet started
  • processing - In progress
  • completed - Finished successfully
  • failed - Verification failed
​
totalEmails
integer
Total emails in the batch.
​
processedEmails
integer
Number of emails processed so far.
​
creditsDeducted
integer
Credits used for this batch.
​
createdAt
string
ISO 8601 timestamp when batch was created.
​
completedAt
string
ISO 8601 timestamp when batch completed (if finished).
​
results
array
Array of verification results (only when completed).
​
analytics
object
Summary analytics (only when completed).
Example Response
{
  "success": true,
  "data": {
    "id": "694fc0cb9e63563857ae8d03",
    "type": "single",
    "status": "completed",
    "totalEmails": 1,
    "analytics": {
      "cleanCount": 0,
      "dirtyCount": 1,
      "unknownCount": 0,
      "cleanPercentage": 0
    },
    "creditsDeducted": 2,
    "startedAt": "2025-12-27T11:19:39.878Z",
    "completedAt": "2025-12-27T11:19:39.878Z",
    "createdAt": "2025-12-27T11:19:39.881Z"
  },
  "meta": {
    "timestamp": "2025-12-27T13:39:37.291Z",
    "requestId": "c6929eab-e9a5-4970-8cc6-089636f541ff",
    "path": "/api/v1/email-verification/694fc0cb9e63563857ae8d03"
  }
}

​
Polling Strategy

For optimal performance, use exponential backoff: 
async function waitForCompletion(verificationId: string) {
  let delay = 1000; // Start with 1 second
  const maxDelay = 10000; // Max 10 seconds

  while (true) {
    const status = await mailbreeze.verification.get(verificationId);

    if (status.status === "completed" || status.status === "failed") {
      return status;
    }

    await new Promise(r => setTimeout(r, delay));
    delay = Math.min(delay * 1.5, maxDelay);
  }
}

​
Errors

CodeHTTP StatusDescription
NOT_FOUND404Verification batch doesn’t exist