Bounceler API Docs

Bounceler Client Bulk Email API

Client-facing bulk email verification API. Authenticate every request with your API key in the `Authorization` header.

Version 1.0.0 OpenAPI 3.0.3

Authentication

Send your API key in the Authorization header for every request.

Authorization: <YOUR_API_KEY>

Code Examples

All examples are rendered into the HTML so crawlers and agents can read them directly without executing JavaScript.

JavaScript

Verify Emails

const response = await fetch('https://app.bounceler.com/api/email/bulk/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    emails: ['first@example.com', 'second@example.com']
  })
});

const data = await response.json();
console.log(data);

Get Status

const response = await fetch('https://app.bounceler.com/api/email/bulk/upd_12345678-1234-1234-1234-123456789abc/status', {
  method: 'GET',
  headers: {
    Authorization: 'YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data.status);
if (data.status !== 'done') {
  console.log('Still processing');
}

Get Results

const response = await fetch('https://app.bounceler.com/api/email/bulk/results', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    request_id: 'upd_12345678-1234-1234-1234-123456789abc'
  })
});

const data = await response.json();
console.log(data.status);
if (data.status === 'done') {
  console.log(data.results);
}

Python

Verify Emails

import requests

response = requests.post(
    'https://app.bounceler.com/api/email/bulk/verify',
    headers={
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'emails': ['first@example.com', 'second@example.com'],
    },
)

print(response.json())

Get Status

import requests

response = requests.get(
    'https://app.bounceler.com/api/email/bulk/upd_12345678-1234-1234-1234-123456789abc/status',
    headers={
        'Authorization': 'YOUR_API_KEY',
    },
)

data = response.json()
print(data['status'])
if data['status'] != 'done':
    print('Still processing')

Get Results

import requests

response = requests.post(
    'https://app.bounceler.com/api/email/bulk/results',
    headers={
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'request_id': 'upd_12345678-1234-1234-1234-123456789abc',
    },
)

data = response.json()
print(data['status'])
if data['status'] == 'done':
    print(data['results'])

Java

Verify Emails

HttpClient client = HttpClient.newHttpClient();
String body = """
{
  \"emails\": [\"first@example.com\", \"second@example.com\"]
}
""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://app.bounceler.com/api/email/bulk/verify"))
    .header("Authorization", "YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Get Status

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://app.bounceler.com/api/email/bulk/upd_12345678-1234-1234-1234-123456789abc/status"))
    .header("Authorization", "YOUR_API_KEY")
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Get Results

HttpClient client = HttpClient.newHttpClient();
String body = """
{
  \"request_id\": \"upd_12345678-1234-1234-1234-123456789abc\"
}
""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://app.bounceler.com/api/email/bulk/results"))
    .header("Authorization", "YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Endpoints

Open raw OpenAPI YAML

Each endpoint below includes request examples, response schemas, and documented error payloads in server-rendered HTML.

POST /api/email/bulk/verify

Verify up to 10,000 emails and return a request id

Submit a bulk verification job for up to 10,000 email addresses in a single request. The API validates the input, checks account credit availability, and creates an async job tied to your API key. Use the returned `request_id` to poll job status or fetch final results.

Request Example

{
  "emails": [
    "first@example.com",
    "second@example.com"
  ]
}

Response Schema

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string"
    },
    "accepted": {
      "type": "boolean"
    },
    "email_summary": {
      "type": "object",
      "properties": {
        "original_counter": {
          "type": "integer"
        },
        "duplication_counter": {
          "type": "integer"
        },
        "valid_counter": {
          "type": "integer"
        },
        "invalid_counter": {
          "type": "integer"
        },
        "valid_sample": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "invalid_sample": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "duplicated_sample": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "original_counter",
        "duplication_counter",
        "valid_counter",
        "invalid_counter",
        "valid_sample",
        "invalid_sample",
        "duplicated_sample"
      ]
    }
  },
  "required": [
    "request_id",
    "accepted",
    "email_summary"
  ]
}

Responses

200 Request accepted 400 Invalid request payload or invalid input values. 401 The `Authorization` header is missing. 402 The API key format is invalid. 403 The API key is deleted or no longer current. 405 The account does not have enough credits to start the bulk request. 500 Unexpected server-side failure.

Error Examples

400 Invalid request payload or invalid input values.

{
  "message": "request_id is required."
}

401 The `Authorization` header is missing.

{
  "message": "Missing authorization key"
}

402 The API key format is invalid.

{
  "message": "Invalid authorization key, make sure you copy the full key."
}

403 The API key is deleted or no longer current.

{
  "message": "Old authorization key"
}

405 The account does not have enough credits to start the bulk request.

{
  "message": "You do not have enough credits for this operation"
}

500 Unexpected server-side failure.

{
  "message": "Internal server error"
}

GET /api/email/bulk/{request_id}/status

Get bulk verification job status

Retrieve the current status of a previously submitted bulk verification job by `request_id`. Use this endpoint for polling while the async verification is still processing.

Response Schema

{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "in_progress"
          ]
        }
      },
      "required": [
        "request_id",
        "status"
      ]
    },
    {
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "done"
          ]
        }
      },
      "required": [
        "request_id",
        "status"
      ]
    }
  ]
}

Responses

200 Current job status 400 Invalid request payload or invalid input values. 401 The `Authorization` header is missing. 402 The API key format is invalid. 403 The API key is deleted or no longer current. 500 Unexpected server-side failure.

Error Examples

400 Invalid request payload or invalid input values.

{
  "message": "request_id is required."
}

401 The `Authorization` header is missing.

{
  "message": "Missing authorization key"
}

402 The API key format is invalid.

{
  "message": "Invalid authorization key, make sure you copy the full key."
}

403 The API key is deleted or no longer current.

{
  "message": "Old authorization key"
}

500 Unexpected server-side failure.

{
  "message": "Internal server error"
}

POST /api/email/bulk/results

Get completed bulk email verification results

Retrieve the final results of a previously submitted bulk verification job by `request_id`. While processing is still running, the API returns an in-progress response so the client can continue polling or switch to the dedicated status endpoint. Once the job finishes, this endpoint returns the completed verification results and summary data.

Request Example

{
  "request_id": "upd_12345678-1234-1234-1234-123456789abc"
}

Response Schema

{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "in_progress"
          ]
        }
      },
      "required": [
        "request_id",
        "status"
      ]
    },
    {
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "done"
          ]
        },
        "summary": {
          "type": "object",
          "additionalProperties": true
        },
        "results": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "upload_uuid": {
                "type": "string",
                "nullable": true
              },
              "email": {
                "type": "string",
                "nullable": true
              },
              "email_index": {
                "type": "integer",
                "nullable": true
              },
              "deliverable": {
                "type": "string",
                "nullable": true,
                "enum": [
                  "DELIVERABLE",
                  "UNDELIVERABLE",
                  "TEMPORARILY_UNDELIVERABLE",
                  "RISKY",
                  "UNKNOWN",
                  "UNCHECKED"
                ]
              },
              "reason": {
                "type": "string",
                "nullable": true
              },
              "format": {
                "type": "string",
                "enum": [
                  "VALID",
                  "INVALID",
                  "UNKNOWN",
                  "UNCHECKED"
                ]
              },
              "dns": {
                "type": "string",
                "enum": [
                  "VALID",
                  "INVALID",
                  "UNKNOWN",
                  "UNCHECKED"
                ]
              },
              "smtp_connect": {
                "type": "string",
                "enum": [
                  "VALID",
                  "INVALID",
                  "UNKNOWN",
                  "UNCHECKED"
                ]
              },
              "smtp_verify": {
                "type": "string",
                "enum": [
                  "VALID",
                  "INVALID",
                  "UNKNOWN",
                  "UNCHECKED"
                ]
              },
              "risk_domain_catch_all": {
                "type": "string",
                "enum": [
                  "VALID",
                  "INVALID",
                  "UNKNOWN",
                  "UNCHECKED"
                ]
              },
              "risk_domain_disposable": {
                "type": "string",
                "enum": [
                  "VALID",
                  "INVALID",
                  "UNKNOWN",
                  "UNCHECKED"
                ]
              },
              "risk_email_role": {
                "type": "string",
                "enum": [
                  "VALID",
                  "INVALID",
                  "UNKNOWN",
                  "UNCHECKED"
                ]
              },
              "risk_email_gibberish": {
                "type": "string",
                "enum": [
                  "VALID",
                  "INVALID",
                  "UNKNOWN",
                  "UNCHECKED"
                ]
              },
              "processed": {
                "type": "boolean"
              },
              "charged": {
                "type": "boolean"
              }
            },
            "required": [
              "upload_uuid",
              "email",
              "email_index",
              "deliverable",
              "reason",
              "format",
              "dns",
              "smtp_connect",
              "smtp_verify",
              "risk_domain_catch_all",
              "risk_domain_disposable",
              "risk_email_role",
              "risk_email_gibberish",
              "processed",
              "charged"
            ]
          }
        }
      },
      "required": [
        "request_id",
        "status",
        "results"
      ]
    }
  ]
}

Responses

200 In-progress or completed response 400 Invalid request payload or invalid input values. 401 The `Authorization` header is missing. 402 The API key format is invalid. 403 The API key is deleted or no longer current. 500 Unexpected server-side failure.

Error Examples

400 Invalid request payload or invalid input values.

{
  "message": "request_id is required."
}

401 The `Authorization` header is missing.

{
  "message": "Missing authorization key"
}

402 The API key format is invalid.

{
  "message": "Invalid authorization key, make sure you copy the full key."
}

403 The API key is deleted or no longer current.

{
  "message": "Old authorization key"
}

500 Unexpected server-side failure.

{
  "message": "Internal server error"
}