Download Validation Result

Learn how to download the results of a completed 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/download-result

This endpoint downloads the validation results for a completed bulk email validation job. Results can be downloaded in CSV or JSON format, and you can optionally filter to only include verified emails.

Request Parameters

The endpoint accepts the following parameters:

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The job ID returned from upload

Query Parameters

Parameter	Type	Required	Description
output	string	No	Output format: csv (default) or json
verifiedOnly	string	No	Filter to only verified emails: true or false (default: false)

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

Download as CSV (default):

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

Download as JSON:

curl -X GET "https://api.simplecold.com/api/v1/api-validation/bulk/550e8400-e29b-41d4-a716-446655440000/download-result?output=json" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -o results.json

Download only verified emails as CSV:

curl -X GET "https://api.simplecold.com/api/v1/api-validation/bulk/550e8400-e29b-41d4-a716-446655440000/download-result?verifiedOnly=true" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -o verified-emails.csv

Success Response (200):

The response will be a file download with the appropriate content type:

• CSV: application/octet-stream with filename {job-id}-validation-result.csv
• JSON: application/octet-stream with filename {job-id}-validation-result.json

Error Response (404):

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

Error Response (400):

{
  "status": "FAILURE",
  "message": "Job is not completed yet"
}

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 downloadResults(jobId, output = "csv", verifiedOnly = false) {
  const params = new URLSearchParams();
  if (output !== "csv") params.append("output", output);
  if (verifiedOnly) params.append("verifiedOnly", "true");

  const url = `https://api.simplecold.com/api/v1/api-validation/bulk/${jobId}/download-result${
    params.toString() ? `?${params.toString()}` : ""
  }`;

  try {
    const response = await fetch(url, {
      method: "GET",
      headers: {
        Authorization: `Bearer ${apiKey}`,
      },
    });

    if (response.ok) {
      const blob = await response.blob();
      const downloadUrl = window.URL.createObjectURL(blob);
      const a = document.createElement("a");
      a.href = downloadUrl;
      a.download = `${jobId}-validation-result.${
        output === "json" ? "json" : "csv"
      }`;
      document.body.appendChild(a);
      a.click();
      window.URL.revokeObjectURL(downloadUrl);
      document.body.removeChild(a);
      console.log("Download started");
    } else {
      const error = await response.json();
      console.error("Download failed:", error.message);
    }
  } catch (error) {
    console.error("Error:", error);
  }
}

// Download all results as CSV
downloadResults(jobId);

// Download only verified emails as JSON
downloadResults(jobId, "json", true);

Using Python (requests)

import requests

api_key = "YOUR_API_KEY_HERE"
job_id = "550e8400-e29b-41d4-a716-446655440000"

def download_results(job_id, output="csv", verified_only=False):
    url = f"https://api.simplecold.com/api/v1/api-validation/bulk/{job_id}/download-result"

    headers = {
        "Authorization": f"Bearer {api_key}"
    }

    params = {}
    if output != "csv":
        params["output"] = output
    if verified_only:
        params["verifiedOnly"] = "true"

    response = requests.get(url, headers=headers, params=params)

    if response.status_code == 200:
        filename = f"{job_id}-validation-result.{'json' if output == 'json' else 'csv'}"
        with open(filename, "wb") as f:
            f.write(response.content)
        print(f"Results saved to {filename}")
    else:
        print(f"Error: {response.status_code} - {response.text}")

# Download all results as CSV
download_results(job_id)

# Download only verified emails as JSON
download_results(job_id, output="json", verified_only=True)

Response Format

CSV Format

The CSV file contains the original columns from your upload plus validation results:

email,status,category,mx_location,site_location,site_language,fail_type,status_message
[email protected],ok,valid,United States,United States,en,none,Email address is valid and deliverable
[email protected],invalid,invalid,United States,United States,en,permanent,Email address does not exist
[email protected],disposable,risky,United States,United States,en,none,Email address is from a disposable provider

JSON Format

The JSON file contains an array of email validation results:

[
  {
    "email": "[email protected]",
    "status": "ok",
    "category": "valid",
    "mx_location": "United States",
    "site_location": "United States",
    "site_language": "en",
    "fail_type": "none",
    "status_message": "Email address is valid and deliverable"
  },
  {
    "email": "[email protected]",
    "status": "invalid",
    "category": "invalid",
    "mx_location": "United States",
    "site_location": "United States",
    "site_language": "en",
    "fail_type": "permanent",
    "status_message": "Email address does not exist"
  }
]

Response Fields

Each result contains the following fields:

Field	Type	Description
email	string	The email address that was validated
status	string	The validation status: ok, invalid, disposable, unknown, etc.
category	string	The category: valid, invalid, risky, unknown
mx_location	string	The geographic location of the mail exchange server
site_location	string	The geographic location of the email provider's website
site_language	string	The language of the email provider's website
fail_type	string	The type of failure if applicable: temporary, permanent, or none
status_message	string	A human-readable description of the validation result

Status Values

The status field can have the following values:

• ok: Email address is valid and deliverable
• invalid: Email address is invalid (syntax error, domain doesn't exist, etc.)
• disposable: Email address is from a disposable email provider
• unknown: Unable to determine the validity of the email address
• syntax_error: Email address has a syntax error

Error Handling

Common Error Responses

404 Not Found

Job Not Found:

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

400 Bad Request

Job Not Completed:

{
  "status": "FAILURE",
  "message": "Job is not completed yet"
}

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 download endpoint:

curl -X GET "https://api.simplecold.com/api/v1/api-validation/bulk/YOUR_JOB_ID/download-result" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -o results.csv

A successful response with file content indicates your integration is working correctly.

Additional Resources

• Using API Key - Learn how to authenticate and use your API key
• Upload Email List - Upload a CSV file for validation
• Get Validation Status - Check the status of your validation job
• Create API Key - Learn how to generate a new API key
• API Documentation - Overview of all API endpoints
• Contact Support - Get help with API integration