Download Result

Download the results of your completed email validation jobs in either CSV or JSON format.

API Reference

Endpoint

GET https://api.cliova.com/v1/webhooks/email-validations/bulk-emails/{id}/download-result?apiKey=${apiKey}&output=${output}&verifiedOnly=${verifiedOnly}

List ID

The id parameter is the identifier of your completed validation job (e.g., list_12345 or 11bb57b9-0901-4fb9-9664-6548cdcd3172)

Parameters

Path Parameters

Parameter	Required	Type	Description
id	Yes	string	The unique identifier of your completed validation job

Query Parameters

Parameter	Required	Type	Description	Default
apiKey	Yes	string	Your API authentication key	-
output	No	string	Output format for results. Options: csv or json	csv
verifiedOnly	No	string	Filter for verified emails only. Options: true or false	false

Code Examples

JavaScript

resultDownloader.js

async function downloadValidationResults(
  apiKey,
  listId,
  output = "csv",
  verifiedOnly = "false",
  outputFilename = `validation_results_${listId}.${output}`
) {
  const baseUrl =
    "https://api.cliova.com/v1/webhooks/email-validations/bulk-emails";
  const url = `${baseUrl}/${listId}/download-result?apiKey=${apiKey}&output=${output}&verifiedOnly=${verifiedOnly}`;

  try {
    const response = await fetch(url, { method: "GET" });
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(errorData.error?.message || "Download failed");
    }

    // Handle response based on output format
    if (output === "json") {
      const jsonData = await response.json();
      // Handle JSON data
      return jsonData;
    } else {
      // Handle CSV download as blob
      const blob = await response.blob();
      const downloadUrl = URL.createObjectURL(blob);

      const link = document.createElement("a");
      link.href = downloadUrl;
      link.download = outputFilename;
      document.body.appendChild(link);
      link.click();
      document.body.removeChild(link);

      setTimeout(() => URL.revokeObjectURL(downloadUrl), 1000);
    }
  } catch (error) {
    console.error("Error downloading results:", error);
  }
}

// ----- Usage Example -----
document.getElementById("downloadButton").addEventListener("click", () => {
  downloadValidationResults("your_api_key", "list_12345", "json", "true");
});

Python

result_downloader.py

import csv
import json
from pathlib import Path
import requests

def download_results(
    api_key: str,
    list_id: str,
    output: str = 'csv',
    verified_only: str = 'false',
    output_path: Path = None
) -> Path:
    if output_path is None:
        output_path = Path(f'validation_results_{list_id}.{output}')

    url = f'https://api.cliova.com/v1/webhooks/email-validations/bulk-emails/{list_id}/download-result'
    params = {
        'apiKey': api_key,
        'output': output,
        'verifiedOnly': verified_only
    }

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

    if output == 'json':
        with open(output_path, 'w') as file:
            json.dump(response.json(), file)
    else:
        with open(output_path, 'wb') as file:
            for chunk in response.iter_content(chunk_size=8192):
                file.write(chunk)

    return output_path

# Usage Example
if __name__ == '__main__':
    try:
        # Download as JSON, verified emails only
        file_path = download_results(
            'your_api_key',
            'list_12345',
            output='json',
            verified_only='true'
        )
        print(f'Results downloaded to: {file_path}')

    except Exception as e:
        print('Download failed:', e)

PHP

ResultDownloader.php

<?php

function downloadValidationResults(
    string $apiKey,
    string $listId,
    string $output = 'csv',
    string $verifiedOnly = 'false',
    string $outputPath = null
): string {
    if ($outputPath === null) {
        $outputPath = "validation_results_{$listId}.{$output}";
    }

    $baseUrl = 'https://api.cliova.com/v1/webhooks/email-validations/bulk-emails';
    $url = sprintf(
        '%s/%s/download-result?apiKey=%s&output=%s&verifiedOnly=%s',
        $baseUrl,
        urlencode($listId),
        urlencode($apiKey),
        urlencode($output),
        urlencode($verifiedOnly)
    );

    $curl = curl_init();

    if ($output === 'json') {
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
        $result = curl_exec($curl);

        if ($result === false) {
            throw new RuntimeException(curl_error($curl));
        }

        file_put_contents($outputPath, $result);
    } else {
        $fp = fopen($outputPath, 'w');
        curl_setopt_array($curl, [
            CURLOPT_URL => $url,
            CURLOPT_FILE => $fp,
            CURLOPT_FOLLOWLOCATION => true,
        ]);

        $result = curl_exec($curl);
        fclose($fp);

        if ($result === false) {
            throw new RuntimeException(curl_error($curl));
        }
    }

    $statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    curl_close($curl);

    if ($statusCode !== 200) {
        throw new RuntimeException("Download failed with status code: {$statusCode}");
    }

    return $outputPath;
}

// Usage Example
try {
    // Download as JSON, verified emails only
    $filePath = downloadValidationResults(
        'your_api_key',
        'list_12345',
        'json',
        'true',
        'validation_results.json'
    );
    echo "File downloaded to: $filePath";
} catch (Exception $e) {
    echo "Download error: " . $e->getMessage();
}

Best Practices

Download Strategy

Efficient Downloads

Follow these guidelines for optimal download handling:

• Verify validation is complete before downloading
• Choose the appropriate output format based on your needs:
  • Use CSV for spreadsheet compatibility and smaller file sizes
  • Use JSON for easier programmatic processing
• Use verifiedOnly='true' to filter out invalid emails
• Save results immediately to avoid re-downloads

Need Help?

Support Resources

• 📘 API Documentation
• 📧 Support Email