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

Browse integrations

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/upd_12345678-1234-1234-1234-123456789abc/results', {
  method: 'GET',
  headers: {
    Authorization: 'YOUR_API_KEY'
  }
});

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.get(
    'https://app.bounceler.com/api/email/bulk/upd_12345678-1234-1234-1234-123456789abc/results',
    headers={
        'Authorization': 'YOUR_API_KEY',
    },
)

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();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://app.bounceler.com/api/email/bulk/upd_12345678-1234-1234-1234-123456789abc/results"))
    .header("Authorization", "YOUR_API_KEY")
    .GET()
    .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

Request Example

{
  "emails": [
    "first@example.com",
    "second@example.com"
  ],
  "callback": "https://client.example.com/bounceler/callback"
}

Response Schema

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string"
    },
    "accepted": {
      "type": "boolean"
    },
    "callback": {
      "type": "string",
      "format": "uri"
    },
    "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}/results

Get bulk verification status or completed email results

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"
              },
              "validationScore": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              }
            },
            "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",
              "validationScore"
            ]
          }
        }
      },
      "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"
}

POST /api/email/bulk/{request_id}/abort

Request abort for a bulk verification job

Response Schema

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string"
    },
    "accepted": {
      "type": "boolean"
    },
    "status": {
      "type": "string",
      "enum": [
        "abort_requested"
      ]
    }
  },
  "required": [
    "request_id",
    "accepted",
    "status"
  ]
}

Responses

200 Abort 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. 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"
}

Bounceler Integrations

Open integrations

Need platform-specific setup steps? Browse the Bounceler integrations guides for HubSpot, Mailchimp, and Klaviyo.