Introduction

Welcome to the Sparkle.io Email Verification API documentation.

This API gives you direct access to Sparkle.io’s email verification service — whether you’re validating emails one at a time, verifying entire lists, or automating list cleanup before launching campaigns.

Using this API helps you:

Improve delivery rates
Reduce bounces
Maintain the integrity of your lead data

You can choose from multiple verification modes — Quick, Thorough, Clever, and Catch-All — depending on your use case, accuracy requirements, and Sparkles budget.

To help you plan usage, rate limits are enforced as follows:

30 requests per second
2,000 requests per minute
50,000 requests per 24 hours

Exceeding the limit will return HTTP 429 (Too Many Requests). We recommend implementing exponential backoff or retries with delay when automating high-volume verifications.

Authentication

All requests must include your API key in the header.

Required Header:

Header Name	Value	Description
x-api-key	YourApiKey	Your unique API key for authentication

You can find your API key in your Sparkle.io dashboard under Settings → API Keys.

Get Account Details

GET: https://api.sparkle.io/v1/sparkle/account

Example cURL:

curl --location 'https://api.sparkle.io/v1/sparkle/account' \
--header 'x-api-key: YourApiKey'

Sample Response:

{
  "error": false,
  "status": 200,
  "message": "Account Connected",
  "data": {
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "account_verification_status": true,
    "apikey_credit_limit": 1000,
    "credits_used": 0
  }
}

Verification Endpoints

Mode	Description	Sparkles Cost
Quick	Fast validation with one SMTP attempt	1 Sparkle per email
Thorough	Multiple attempts for improved accuracy	2 Sparkles per email
Catch-All	Uses advanced Catch-All domain detection	5 Sparkles per email
Clever	Smart escalation through Quick → Thorough → Catch-All as needed	Varies (1–5 Sparkles/email)

Single Verification - Quick

POST: https://api.sparkle.io/v1/email-verifier/single/quick

Request Body:

{
  "email": "[email protected]"
}

Example cURL:

curl --location 'https://api.sparkle.io/v1/email-verifier/single/quick' \
--header 'x-api-key: YourApiKey' \
--data-raw '{ "email": "[email protected]" }'

Single Verification - Thorough

POST: https://api.sparkle.io/v1/email-verifier/single/thorough

Request Body:

{
  "email": "[email protected]"
}

Example cURL:

curl --location 'https://api.sparkle.io/v1/email-verifier/single/thorough' \
--header 'x-api-key: YourApiKey' \
--data-raw '{ "email": "[email protected]" }'

Single Verification - Catchall

POST: https://api.sparkle.io/v1/email-verifier/single/catchall

Request Body:

{
  "email": "[email protected]"
}

Example cURL:

curl --location 'https://api.sparkle.io/v1/email-verifier/single/catchall' \
--header 'x-api-key: YourApiKey' \
--data-raw '{ "email": "[email protected]" }'

Single Verification - Clever

POST: https://api.sparkle.io/v1/email-verifier/single/clever

This smart mode uses a waterfall approach:

Starts with Quick (1 sparkle)
Escalates to Thorough (2 sparkles) if needed
Ends with Catch-All (5 sparkles) only when required

Request Body:

{
  "email": "[email protected]"
}

Example cURL:

curl --location 'https://api.sparkle.io/v1/email-verifier/single/clever' \
--header 'x-api-key: YourApiKey' \
--data-raw '{ "email": "[email protected]" }'

Bulk Verification — Quick

POST: https://api.sparkle.io/v1/email-verifier/bulk/quick

Request Body:

{
  "list_name": "test-123",
  "email_list": [
    { "email": "[email protected]" }
  ]
}

Bulk Verification — Thorough

POST: https://api.sparkle.io/v1/email-verifier/bulk/thorough

Request Body:

{
  "list_name": "test-123",
  "email_list": [
    { "email": "[email protected]" }
  ]
}

Bulk Verification — Catchall

POST: https://api.sparkle.io/v1/email-verifier/bulk/catchall

Request Body:

{
  "list_name": "test-123",
  "email_list": [
    { "email": "[email protected]" }
  ]
}

Bulk Verification — Clever

POST: https://api.sparkle.io/v1/email-verifier/bulk/clever

Request Body:

{
  "list_name": "test-123",
  "email_list": [
    { "email": "[email protected]" }
  ]
}

Bulk Verification Status Check

Track the progress of your submitted list.

GET: https://api.sparkle.io/v1/email-verifier/bulk/counts/{id}

Example Response:

{
  "error": false,
  "status": 200,
  "message": "Success",
  "data": {
    "_id": "679367388c77ff4930caccaa",
    "uuid": "5288e585-a590-4f92-9bad-3e506d82f507",
    "list_name": "test-123",
    "total_email_verify_count": 1,
    "verify_status": 1, // 0 = processing, 1 = completed
    "verified_count": 0,
    "safe_count": 0,
    "unsafe_count": 0,
    "unknown_count": 0
  }
}

Bulk Verification Results

GET: https://api.sparkle.io/v1/email-verifier/bulk/{id}?limit={total_email_verify_count}

Replace {total_email_verify_count} with the number of emails submitted in the list.

Response Structure:

{
  "error": false,
  "status": 200,
  "message": "Success",
  "data": [
    {
      "_id": "6790cb14b7598ae50cbcca1f",
      "uuid": "a1826855-fc6a-4e09-a4e9-8535307e1046",
      "email_verifier_id": "d7f4ed21-766d-4a9a-96d7-8cfcb0f54788",
      "email": "[email protected]",
      "verify_details": {
        "status": {
          "error": true,
          "result": "unsafe",
          "message": "SMTP connection failed.",
          "sub_status": "MailboxDoesNotExist"
        },
        "multi_status": {
          "isValidSyntax": true,
          "isTempEmail": false,
          "isValidDomain": true,
          "isCatchAllDomain": false,
          "isRoleBasedAccount": false,
          "isValidSmtp": false,
          "isValidEmail": false,
          "isTarpitting": false,
          "isEmailGreyListed": false,
          "isSafeToSend": false,
          "isDeliverable": false,
          "canConnectSmtp": false,
          "isParkedDomain": false,
          "isFreeEmailAccount": true,
          "mxRecord": "gmail-smtp-in.l.google.com",
          "sub_status": "MailboxDoesNotExist"
        }
      },
      "verify_status": 1
    }
  ]
}

Key fields:

result: valid, invalid, unknown, unsafe
message: Human-readable status
sub_status: Explains why it’s unsafe or unknown (e.g., MailboxDoesNotExist, CatchAllDomain)

Happy sparkling! ✨