API Documentation | BulkCheck.io

Overview#

The BulkCheck API allows you to verify email addresses programmatically. With a single POST request you can validate up to 1,000 emails at once and receive detailed results including validity status and failure reasons.

🔒

Protocol

HTTPS

{ }

Format

JSON

🔑

Auth

API Key

Authentication#

All API requests require authentication via your API key. You can find your key in the Dashboard → API Keys page. API access is available on Starter plans and above.

Pass your key using either of these methods:

Option 1 — Authorization Header (Recommended)

http

Authorization: Bearer bck_live_your_api_key_here

Option 2 — x-api-key Header

http

x-api-key: bck_live_your_api_key_here

Keep your API key secret

Never expose your API key in client-side code, public repos, or browser requests. Use server-side calls only.

Base URL#

All API requests should be made to:

text

https://bulkcheck.io/api/v1

Verify Emails#

POST/api/v1/verify

Validate one or more email addresses. Returns results for each email including whether it's valid and the reason for failure (if any).

Parameters

Field	Type	Required	Description
emails	string[]	Required	Array of email addresses to verify. Max 1,000 per request.

Request Format#

json

{
  "emails": [
    "john@company.com",
    "jane@example.org",
    "invalid@fake-domain-12345.xyz"
  ]
}

Response Format#

A successful response includes an overall summary and an array of individual results:

json

{
  "success": true,
  "total": 3,
  "valid": 2,
  "invalid": 1,
  "results": [
    {
      "email": "john@company.com",
      "valid": true,
      "reason": null
    },
    {
      "email": "jane@example.org",
      "valid": true,
      "reason": null
    },
    {
      "email": "invalid@fake-domain-12345.xyz",
      "valid": false,
      "reason": "Domain does not exist"
    }
  ]
}

Result Fields

Field	Type	Description
success	boolean	Whether the API call succeeded
total	number	Total emails processed
valid	number	Count of valid emails
invalid	number	Count of invalid emails
results[].email	string	The email address that was checked
results[].valid	boolean	Whether the email is valid
results[].reason	string \| null	Reason for failure, or null if valid

Code Examples#

cURL

bash

curl -X POST https://bulkcheck.io/api/v1/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["test@gmail.com", "user@company.com"]
  }'

Python

python

import requests

API_KEY = "YOUR_API_KEY"

response = requests.post(
    "https://bulkcheck.io/api/v1/verify",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "emails": ["test@gmail.com", "user@company.com"]
    },
)

data = response.json()
print(f"Valid: {data['valid']} / {data['total']}")

for result in data["results"]:
    status = "✅" if result["valid"] else "❌"
    print(f"  {status} {result['email']}: {result['reason'] or 'OK'}")

Node.js

javascript

const API_KEY = "YOUR_API_KEY";

const response = await fetch("https://bulkcheck.io/api/v1/verify", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    emails: ["test@gmail.com", "user@company.com"],
  }),
});

const data = await response.json();
console.log(`Valid: ${data.valid} / ${data.total}`);

data.results.forEach((r) => {
  console.log(`  ${r.valid ? "✅" : "❌"} ${r.email}: ${r.reason || "OK"}`);
});

PHP

php

<?php
$apiKey = "YOUR_API_KEY";

$ch = curl_init("https://bulkcheck.io/api/v1/verify");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer $apiKey",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "emails" => ["test@gmail.com", "user@company.com"],
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo "Valid: {$data['valid']} / {$data['total']}\n";

foreach ($data['results'] as $r) {
    $icon = $r['valid'] ? '✅' : '❌';
    echo "  $icon {$r['email']}: " . ($r['reason'] ?? 'OK') . "\n";
}
?>

Rate Limits#

API call limits are enforced per calendar month and reset automatically. When your quota is exhausted, the API returns 429 Too Many Requests.

Plan	API Calls / Month	Emails / Request
Free	No API access	—
Starter ($19/mo)	5,000	1,000
Growth ($49/mo)	25,000	1,000
Pro ($99/mo)	Unlimited*	1,000
Enterprise ($249/mo)	Unlimited*	1,000

* Subject to fair use policy. Abusive usage may be rate-limited.

Error Codes#

The API uses standard HTTP status codes. Errors include a JSON body with an error field describing the issue.

Status	Meaning	Description
200	OK	Request succeeded. Check the results array.
400	Bad Request	Invalid request body — missing or empty emails array.
401	Unauthorized	Missing, invalid, or deactivated API key.
403	Forbidden	Your plan does not include API access.
429	Too Many Requests	Monthly API call quota exhausted. Upgrade your plan or wait for the next billing cycle.
500	Server Error	Unexpected server error. Contact support if this persists.

Error Response Example

json

{
  "error": "API call quota exhausted for this month.",
  "used": 5000,
  "limit": 5000
}

Ready to integrate?

Generate your API key and start verifying emails in under 60 seconds.

Get Your API Key View Pricing