Upload Bulk List

This guide explains how to validate large lists of email addresses using our bulk validation API endpoint.

Sample Data Template

Sample Data Format

We provide a sample email list template that shows the correct CSV format. Your CSV file should contain the following columns:

• email (required)
• name (optional)
• company (optional)

API Reference

Endpoint

POST https://api.cliova.com/v1/webhooks/email-validations/bulk-emails?apiKey=${apiKey}&name=${listName}

Parameters

Query Parameters

Parameter	Required	Type	Description
apiKey	Yes	string	Your API authentication key
name	Yes	string	Unique name for your email list

Request Body

Parameter	Required	Type	Description
file	Yes	File	CSV file containing email addresses

Code Examples

JavaScript

emailValidator.js

const validateEmails = async (apiKey, listName, csvFile) => {
  const formData = new FormData();
  formData.append("file", csvFile);

  const response = await fetch(
    `https://api.cliova.com/v1/webhooks/email-validations/bulk-emails?apiKey=${apiKey}&name=${listName}`,
    { method: "POST", body: formData }
  );

  if (!response.ok) {
    const errorData = await response.json();
    throw new Error(errorData.error?.message || "Validation request failed");
  }
  return response.json();
};

// Usage Example
document
  .querySelector('input[type="file"]')
  .addEventListener("change", async (event) => {
    try {
      const result = await validateEmails(
        "your_api_key",
        "my_email_list",
        event.target.files[0]
      );
      console.log("Validation started:", result);
    } catch (error) {
      console.error("Validation failed:", error);
    }
  });

Python

email_validator.py

import requests

def validate_bulk_emails(api_key, csv_path, list_name):
    with open(csv_path, 'rb') as f:
        files = {'file': f}
        params = {'apiKey': api_key, 'name': list_name}
        response = requests.post(
            'https://api.cliova.com/v1/webhooks/email-validations/bulk-emails',
            params=params,
            files=files
        )
    response.raise_for_status()
    return response.json()

# Usage Example
if __name__ == '__main__':
    try:
        result = validate_bulk_emails('your_api_key', 'emails.csv', 'my_email_list')
        print("Validation started:", result)
    except Exception as e:
        print("Validation failed:", e)

PHP

EmailValidator.php

<?php

function validateBulkEmails($apiKey, $csvPath, $listName) {
    if (!file_exists($csvPath)) {
        throw new Exception("CSV file not found: $csvPath");
    }

    $url = sprintf(
        'https://api.cliova.com/v1/webhooks/email-validations/bulk-emails?apiKey=%s&name=%s',
        urlencode($apiKey),
        urlencode($listName)
    );

    $file = new CURLFile($csvPath, 'text/csv', basename($csvPath));
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, ['file' => $file]);
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Accept: application/json']);

    $response = curl_exec($ch);
    if ($response === false) {
        throw new Exception(curl_error($ch));
    }

    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        throw new Exception("API request failed with status code: $httpCode");
    }
    return json_decode($response, true);
}

// Usage Example
try {
    $result = validateBulkEmails('your_api_key', 'emails.csv', 'my_email_list');
    echo "Validation started: " . json_encode($result, JSON_PRETTY_PRINT);
} catch (Exception $e) {
    echo "Validation failed: " . $e->getMessage();
}

Response Examples

Success Response

{
  "code": "SUCCESS",
  "message": "Successfully performed operation.",
  "payload": {
    "id": "10a65f89-5de0-403a-a1ea-8ceea94a4ad9",
    "name": "Email List",
    "orgId": "8e69b5b1248716cf",
    "totalEmails": 20000,
    "totalValidEmails": 0,
    "totalCreditsUsed": 20000,
    "status": "IN PROGRESS",
    "environment": "production",
    "apiKeyId": "6510a65f-10a65f8-90a25h8",
    "userId": "user_2sc3RYDvOtBEXNHtXH7Qm8jaFUW",
    "updatedAt": "2025-02-12T12:43:13.087Z",
    "createdAt": "2025-02-12T12:43:13.087Z",
    "deletedAt": null
  },
  "requestId": "31ed2794168f7826"
}

Error Response

{
  "success": false,
  "message": "The uploaded file is not a valid CSV file"
}

Best Practices

File Preparation

• Follow the example template format exactly
• Remove duplicate emails

Error Handling

• Implement proper error handling
• Log failed requests
• Use exponential backoff for retries

Security

• Never hardcode API keys
• Use environment variables
• Validate file contents before upload

Rate Limits

Be mindful of our rate limits:

• Maximum 10,00000 emails per file

Need Help?

Support Resources

• 📘 API Documentation
• 📧 Support Email