Skip to main content

Upload Email List

Learn how to upload a CSV file containing email addresses for bulk validation 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: POST /api/v1/api-validation/bulk

This endpoint uploads a CSV file containing email addresses for asynchronous bulk validation. The validation job will be processed in the background, and you can check its status and download results when complete.

Request Format​

The endpoint accepts a multipart/form-data request with a CSV file.

Request Parameters​

ParameterTypeRequiredDescription
filefileYesCSV file containing email addresses (max 7MB)

CSV File Format​

Your CSV file should contain email addresses in one of the following formats:

Option 1: Single column with header

email
[email protected]
[email protected]
[email protected]

Option 2: Single column without header

[email protected]
[email protected]
[email protected]

Option 3: Multiple columns (email column will be auto-detected)

name,email,company
John Doe,[email protected],Acme Corp
Jane Smith,[email protected],Tech Inc

The API will automatically detect the email column in your CSV file.

File Size Limits​

  • Maximum file size: 7MB
  • Files larger than 7MB will be rejected with a 400 Bad Request error

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 upload a CSV file using cURL:

curl -X POST "https://api.simplecold.com/api/v1/api-validation/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -F "file=@/path/to/your/emails.csv"

Success Response (200):

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

Error Response (400):

{
  "status": "FAILURE",
  "message": "File is required"
}

Error Response (401):

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

Error Response (429):

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

Using JavaScript (Fetch API)​

const apiKey = "YOUR_API_KEY_HERE";
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];

const formData = new FormData();
formData.append("file", file);

fetch("https://api.simplecold.com/api/v1/api-validation/bulk", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
  body: formData,
})
  .then((response) => response.json())
  .then((data) => {
    if (data.status === "SUCCESS") {
      const job = data.payload;
      console.log(`Job ID: ${job.id}`);
      console.log(`Total emails: ${job.totalEmails}`);
      console.log(`Status: ${job.status}`);

      // Store the job ID to check status later
      localStorage.setItem("bulkJobId", job.id);
    } else {
      console.error("Upload failed:", data.message);
    }
  })
  .catch((error) => console.error("Error:", error));

Using Python (requests)​

import requests

api_key = "YOUR_API_KEY_HERE"
url = "https://api.simplecold.com/api/v1/api-validation/bulk"

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

# Open the CSV file
with open("emails.csv", "rb") as file:
    files = {
        "file": ("emails.csv", file, "text/csv")
    }

    response = requests.post(url, headers=headers, files=files)

    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"Total emails: {job['totalEmails']}")
            print(f"Status: {job['status']}")
        else:
            print(f"Error: {data.get('message')}")
    else:
        print(f"Error: {response.status_code} - {response.text}")

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
statusstringCurrent status of the job (QUEUE, IN_PROGRESS, COMPLETED, FAILED, CANCELED)
createdAtstringISO timestamp when the job was created

Job Status Values​

After uploading, the job will have one of the following statuses:

  • 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

Next Steps​

After uploading your file:

  1. Check Job Status: Use the job id to check the validation status

  2. Download Results: Once the job status is COMPLETED, download the results

Error Handling​

Common Error Responses​

400 Bad Request​

File is Required:

{
  "status": "FAILURE",
  "message": "File is required"
}

File Too Large:

{
  "status": "FAILURE",
  "message": "File size exceeds maximum limit of 7MB"
}

Invalid File Type:

{
  "status": "FAILURE",
  "message": "Only CSV files are supported"
}

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 bulk upload endpoint:

# Create a test CSV file
echo "email" > test-emails.csv
echo "[email protected]" >> test-emails.csv
echo "[email protected]" >> test-emails.csv

# Upload the file
curl -X POST "https://api.simplecold.com/api/v1/api-validation/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -F "[email protected]"

A successful response with "status": "SUCCESS" and a job id indicates your integration is working correctly.

Additional Resources​