Skip to main content

Get Validation Status

Learn how to check the status of a bulk email validation job using the SimpleCold Email Validation API.

Authentication​

All API requests require authentication using a Bearer token in the Authorization header. Your API key serves as this Bearer token.

For detailed information on authentication, see the Using API Key guide.

Authorization Header Format​

Include your API key in the Authorization header using the following format:

Authorization: Bearer <your-api-key>

Replace <your-api-key> with your actual API key that you generated from the dashboard.

API Base URL​

All API endpoints are accessed through the following base URL:

https://api.simplecold.com/api/v1

Endpoint​

Endpoint: GET /api/v1/api-validation/bulk/:id/status

This endpoint retrieves the current status and progress of a bulk email validation job. Use this to monitor your validation jobs and determine when they're ready for download.

Request Parameters​

The endpoint accepts the following path parameter:

ParameterTypeRequiredDescription
idstringYesThe job ID returned from upload

Rate Limits​

  • 10 requests per minute per API key
  • If you exceed the rate limit, you'll receive a 429 Too Many Requests response

Request Examples​

Using cURL​

Here's how to check the status of a validation job using cURL:

curl -X GET "https://api.simplecold.com/api/v1/api-validation/bulk/550e8400-e29b-41d4-a716-446655440000/status" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE"

Success Response (200) - Job in Queue:

{
  "status": "SUCCESS",
  "payload": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "emails",
    "totalEmails": 1000,
    "totalValidEmails": 0,
    "totalCreditsUsed": 0,
    "status": "QUEUE",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Success Response (200) - Job in Progress:

{
  "status": "SUCCESS",
  "payload": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "emails",
    "totalEmails": 1000,
    "totalValidEmails": 450,
    "totalCreditsUsed": 1000,
    "status": "IN_PROGRESS",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:35:00Z"
  }
}

Success Response (200) - Job Completed:

{
  "status": "SUCCESS",
  "payload": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "emails",
    "totalEmails": 1000,
    "totalValidEmails": 850,
    "totalCreditsUsed": 1000,
    "status": "COMPLETED",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:45:00Z"
  }
}

Error Response (404):

{
  "status": "FAILURE",
  "message": "Job not found"
}

Error Response (401):

{
  "status": "FAILURE",
  "message": "Invalid API key"
}

Using JavaScript (Fetch API)​

const apiKey = "YOUR_API_KEY_HERE";
const jobId = "550e8400-e29b-41d4-a716-446655440000";

async function checkJobStatus(jobId) {
  const response = await fetch(
    `https://api.simplecold.com/api/v1/api-validation/bulk/${jobId}/status`,
    {
      method: "GET",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
      },
    }
  );

  const data = await response.json();

  if (data.status === "SUCCESS") {
    const job = data.payload;
    console.log(`Job ID: ${job.id}`);
    console.log(`Status: ${job.status}`);
    console.log(`Total emails: ${job.totalEmails}`);
    console.log(`Valid emails: ${job.totalValidEmails}`);
    console.log(`Credits used: ${job.totalCreditsUsed}`);

    if (job.status === "COMPLETED") {
      console.log("Job completed! Ready to download results.");
    } else if (job.status === "IN_PROGRESS") {
      const progress = ((job.totalValidEmails / job.totalEmails) * 100).toFixed(
        1
      );
      console.log(`Progress: ${progress}%`);
    }
  } else {
    console.error("Error:", data.message);
  }
}

// Poll status every 10 seconds until completed
async function pollJobStatus(jobId) {
  const interval = setInterval(async () => {
    await checkJobStatus(jobId);
    const response = await fetch(
      `https://api.simplecold.com/api/v1/api-validation/bulk/${jobId}/status`,
      {
        method: "GET",
        headers: {
          Authorization: `Bearer ${apiKey}`,
        },
      }
    );
    const data = await response.json();

    if (data.status === "SUCCESS" && data.payload.status === "COMPLETED") {
      clearInterval(interval);
      console.log("Job completed!");
    }
  }, 10000); // Check every 10 seconds
}

Using Python (requests)​

import requests
import time

api_key = "YOUR_API_KEY_HERE"
job_id = "550e8400-e29b-41d4-a716-446655440000"
url = f"https://api.simplecold.com/api/v1/api-validation/bulk/{job_id}/status"

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

def check_job_status(job_id):
    response = requests.get(url, headers=headers)

    if response.status_code == 200:
        data = response.json()
        if data.get("status") == "SUCCESS":
            job = data.get("payload")
            print(f"Job ID: {job['id']}")
            print(f"Status: {job['status']}")
            print(f"Total emails: {job['totalEmails']}")
            print(f"Valid emails: {job['totalValidEmails']}")
            print(f"Credits used: {job['totalCreditsUsed']}")

            if job['status'] == 'COMPLETED':
                print("Job completed! Ready to download results.")
                return True
            elif job['status'] == 'IN_PROGRESS':
                progress = (job['totalValidEmails'] / job['totalEmails']) * 100
                print(f"Progress: {progress:.1f}%")
        else:
            print(f"Error: {data.get('message')}")
    else:
        print(f"Error: {response.status_code} - {response.text}")

    return False

# Poll status every 10 seconds until completed
def poll_job_status(job_id):
    while True:
        if check_job_status(job_id):
            break
        time.sleep(10)  # Wait 10 seconds before next check

Response Fields​

The response payload contains the following fields:

FieldTypeDescription
idstringUnique identifier for the validation job
namestringName of the uploaded file (without extension)
totalEmailsnumberTotal number of email addresses in the file
totalValidEmailsnumberNumber of valid email addresses found
totalCreditsUsednumberTotal credits consumed for this job
statusstringCurrent status of the job
createdAtstringISO timestamp when the job was created
updatedAtstringISO timestamp when the job was last updated

Job Status Values​

The status field can have the following values:

  • QUEUE: Job is queued and waiting to be processed
  • IN_PROGRESS: Job is currently being processed
  • COMPLETED: Job has completed successfully
  • FAILED: Job failed during processing
  • CANCELED: Job was canceled
  • CANCELING: Job is being canceled

Polling Strategy​

Since bulk validation jobs are processed asynchronously, you'll need to poll the status endpoint periodically. Here are some recommendations:

  • Initial wait: Wait 5-10 seconds after upload before first status check
  • Polling interval: Check every 10-30 seconds depending on job size
  • Stop polling: When status is COMPLETED, FAILED, or CANCELED

Error Handling​

Common Error Responses​

404 Not Found​

Job Not Found:

{
  "status": "FAILURE",
  "message": "Job not found"
}

401 Unauthorized​

Invalid or Missing API Key:

{
  "status": "FAILURE",
  "message": "Invalid API key"
}

Missing Authorization Header:

{
  "status": "FAILURE",
  "message": "Authorization header is required"
}

429 Too Many Requests​

Rate Limit Exceeded:

{
  "status": 429,
  "error": "Rate limit exceeded. Maximum 10 requests per minute per API key."
}

Testing Your Integration​

You can quickly test the status endpoint:

curl -X GET "https://api.simplecold.com/api/v1/api-validation/bulk/YOUR_JOB_ID/status" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE"

A successful response with "status": "SUCCESS" indicates your integration is working correctly.

Additional Resources​