# BounceBan API Documentation (Full)

> Complete API documentation for BounceBan email verification service, in a single file for AI agents. Index version: https://bounceban.com/public/doc/llms.txt

---

# BounceBan API Introduction

> BounceBan is an email verification API. It verifies all kinds of emails and specializes in verifying emails that are accept-all (catch-all) or protected by SEGs (Secure Email Gateways). Instead of marking all accept-all emails as risky, BounceBan identifies which of them are actually deliverable.

## Base URLs

| API | Base URL |
| --- | --- |
| All standard endpoints | `https://api.bounceban.com` |
| Waterfall single verification (Clay, n8n, etc.) | `https://api-waterfall.bounceban.com` |

## Authentication

All endpoints require an API key sent in the `Authorization` header (no `Bearer` prefix):

```
Authorization: YOUR_API_KEY
```

Get your API key, set IP whitelist, and track usage at: https://bounceban.com/app/api/settings

```bash
curl "https://api.bounceban.com/v1/account" \
  -H "Authorization: YOUR_API_KEY"
```

## Credits

- Each successful verification costs **1 credit** (single or bulk).
- Credits are deducted for every request to `/v1/verify/single`, even for repeated verification of the same email.
- For the waterfall endpoint, retrying the same email within 30 minutes of the initial request does **not** deduct extra credits.
- When `disable_catchall_verify=1` and the result is `unknown` with `score: -1`, the credit cost is 0.
- For bulk tasks, credits for `unknown` results are refunded when the task finishes.
- The `/v1/check` endpoint uses a **separate** Check Plan credit balance.
- Buy credits: https://bounceban.com/pricing. Test credits: contact dev@bounceban.com.

## Verification results

Every verified email gets a `result` and a `score`:

| Field | Values | Meaning |
| --- | --- | --- |
| `result` | `deliverable` | Safe to send. |
| | `risky` | May bounce; check `score` (higher is better). |
| | `undeliverable` | Will bounce; do not send. |
| | `unknown` | Verification could not determine a result. |
| `score` | `0`-`100` | Deliverability confidence; higher is better. |

Additional boolean flags per email: `is_disposable`, `is_accept_all`, `is_role`, `is_free`. `mx_records` (array) and `smtp_provider` (string, e.g. `Google`) are also returned when available.

## Task status values

| Status | Meaning |
| --- | --- |
| `success` | Verification finished; final result included. |
| `verifying` | Still verifying (e.g. greylisting). Poll status endpoint or use a webhook. Do NOT resubmit - each request costs 1 credit. |
| `queue` | Account rate limit reached; email queued. Poll or use webhook. |

## Verification modes

| Mode | Description |
| --- | --- |
| `regular` | Default. Does not assume the email's domain matches the owner's current company website. |
| `deepverify` | Assumes the email's domain matches the owner's current company website (e.g. from LinkedIn). Improves success rate for accept-all emails. Learn more: https://support.bounceban.com/article/what-is-deepverify |

## Choosing the right endpoint

| Scenario | Use |
| --- | --- |
| One HTTP request, wait for result (Clay, n8n, Zapier-like waterfall) | `GET https://api-waterfall.bounceban.com/v1/verify/single` |
| Async single verification with polling or webhook | `GET /v1/verify/single` + `GET /v1/verify/single/status` |
| Verify a list of emails (up to ~500,000 per task) | `POST /v1/verify/bulk` |
| Verify emails from a CSV file (max 25 MB) | `POST /v1/verify/bulk/file` |
| Quick syntax/domain/role check (no SMTP verification) | `GET /v1/check` |
| Credits balance and rate limits | `GET /v1/account` |

## Rate limits

Default per-account limits (check live values via `GET /v1/account`):

| Endpoint | Limit |
| --- | --- |
| `/v1/verify/single` | 25 per second |
| `/v1/verify/single/status` | 25 per second |
| `/v1/verify/bulk` | 3 per second |
| `/v1/verify/bulk/status` | 25 per second |
| `/v1/verify/bulk/export` | 25 per second |
| `/v1/verify/bulk/dump` | 25 per second |
| `/v1/account` | 5 per second |

Request a higher limit: https://forms.gle/3De4UMZKpxPiPv5M8

## Data retention

Verification results are available for **90 days** after verification.

## Resources

- Interactive API reference (Redoc): https://bounceban.com/public/doc/api.html
- OpenAPI 3.0 spec: https://bounceban.com/public/doc/api.yaml
- Postman workspace: https://www.postman.com/galactic-comet-480286/workspace/bounceban-developers
- Support: dev@bounceban.com

---

# Single Verification

Verify one email address at a time. Three endpoints:

1. **Waterfall endpoint** - one synchronous request, recommended for Clay, n8n and similar services.
2. **Standard endpoint** - 15-second timeout, then async via polling or webhook.
3. **Status endpoint** - poll for an async result.

---

## Waterfall single verification (recommended for Clay / n8n)

```
GET https://api-waterfall.bounceban.com/v1/verify/single
```

**Note: different base URL** (`api-waterfall.bounceban.com`). Holds the connection open until the result is ready (default 80 s, configurable). No separate polling call needed. If it times out with HTTP `408`, send the same request again - retries within 30 minutes of the initial request for the same email don't deduct credits.

### Parameters (query)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | Yes | The email to verify. |
| `mode` | string | No | `regular` (default) or `deepverify`. |
| `url` | string | No | Webhook URL to receive the result via HTTP POST. Event header: `event-type: single.email_verification_finished`. |
| `timeout` | integer | No | Timeout in seconds, 30-300, default 80. Must not exceed your own service's timeout limit. |
| `disable_catchall_verify` | string | No | `0` (default) or `1`. When `1`, only basic SMTP verification runs; catch-all/SEG-protected emails return `result: "unknown"`, `score: -1`, cost 0 credits. |

### Example request

```bash
curl "https://api-waterfall.bounceban.com/v1/verify/single?email=dev@bounceban.com" \
  -H "Authorization: YOUR_API_KEY"
```

### Example response (200)

```json
{
  "id": "wf502abcde",
  "status": "success",
  "email": "dev@bounceban.com",
  "result": "deliverable",
  "score": 99,
  "is_disposable": false,
  "is_accept_all": false,
  "is_role": true,
  "is_free": false,
  "mx_records": ["alt1.aspmx.l.google.com", "aspmx.l.google.com"],
  "smtp_provider": "Google",
  "mode": "regular",
  "verify_at": "2022-11-16T07:21:24.943Z",
  "credits_consumed": 1.0,
  "credits_remaining": 375214.0
}
```

### Timeout response (408)

```json
{
  "id": "8416f480",
  "error": "Verification timeout",
  "message": "The email verification request timed out after 80 seconds. Please submit the email again. You won't be charged for resubmitting the same email within 30 minutes of the initial request."
}
```

On `408`: retry the same request. Retries within 30 minutes are free.

Tutorials: [Clay](https://support.bounceban.com/article/how-to-use-bounceban-with-clay) | [n8n](https://support.bounceban.com/article/how-to-use-the-n8n-node)

---

## Standard single verification

```
GET https://api.bounceban.com/v1/verify/single
```

15-second timeout. If verification finishes in time, the full result is returned. Otherwise the response contains `status: "verifying"` and an `id` - get the final result by polling `/v1/verify/single/status` or via webhook (`url` parameter).

**Costs 1 credit per request, even for the same email.** Never resubmit while `status` is `verifying` or `queue`.

### Parameters (query)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | Yes | The email to verify. |
| `mode` | string | No | `regular` (default) or `deepverify`. |
| `url` | string | No | Webhook URL for the result. Event header: `event-type: single.email_verification_finished`. |
| `disable_catchall_verify` | string | No | `0` (default) or `1`. See waterfall endpoint above. |

### Example request

```bash
curl "https://api.bounceban.com/v1/verify/single?email=dev@bounceban.com" \
  -H "Authorization: YOUR_API_KEY"
```

### Example response - finished (200)

```json
{
  "id": "502abcde",
  "status": "success",
  "email": "dev@bounceban.com",
  "result": "deliverable",
  "score": 99,
  "is_disposable": false,
  "is_accept_all": false,
  "is_role": true,
  "is_free": false,
  "mx_records": ["alt1.aspmx.l.google.com", "aspmx.l.google.com"],
  "smtp_provider": "Google",
  "verify_at": "2022-11-16T07:21:24.943Z",
  "credits_consumed": 1.0,
  "credits_remaining": 375214.0
}
```

### Example response - still verifying (200)

```json
{
  "id": "502abcde",
  "msg": "The email verification process is not yet complete.",
  "status": "verifying",
  "try_again_at": 1731286696
}
```

`try_again_at` is the recommended Unix timestamp for the next poll.

---

## Get single verification result (poll)

```
GET https://api.bounceban.com/v1/verify/single/status
```

Free - does not cost credits. Results available for 90 days.

### Parameters (query)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The `id` returned by `/v1/verify/single`. |

### Polling rules (important for agents)

- Cap polling at **10 requests per `id` per 5 minutes**.
- After 5 minutes with no result, stop polling and start a new verification request.
- Prefer webhooks over polling: pass a `url` parameter in the original `/v1/verify/single` request.

### Example request

```bash
curl "https://api.bounceban.com/v1/verify/single/status?id=502abcde" \
  -H "Authorization: YOUR_API_KEY"
```

Responses have the same shape as `/v1/verify/single` above (`success` or `verifying`).

---

## Error responses (all single endpoints)

| HTTP status | Meaning |
| --- | --- |
| `400` | Invalid parameter. |
| `401` | Authorization missing or invalid. |
| `403` | Insufficient credits. Body includes `credits_required`, `credits_remaining`, `message`. |
| `405` | Account blocked. |
| `408` | Verification timeout (waterfall endpoint only) - retry the same request. |
| `429` | Rate limited. |
| `500` | Unexpected error. |

---

# Bulk Verification

Verify a list of emails as an asynchronous task. Typical flow:

1. Create a task: `POST /v1/verify/bulk` (JSON list) or `POST /v1/verify/bulk/file` (CSV upload) -> returns task `id`.
2. Track progress: `GET /v1/verify/bulk/status` (or `url_finished` webhook).
3. Get results: `GET /v1/verify/bulk/dump` (JSON), `POST /v1/verify/bulk/emails` (specific emails), or `POST /v1/verify/bulk/export` (CSV download link).
4. Optionally delete: `POST /v1/verify/bulk/destroy`.

All endpoints use base URL `https://api.bounceban.com` and the `Authorization: YOUR_API_KEY` header.

---

## Create bulk task from a list of emails

```
POST https://api.bounceban.com/v1/verify/bulk
Content-Type: application/json
```

Recommended max: **500,000 emails per task** (contact support for more). A dynamic soft limit applies to concurrent verifying emails per account.

### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `emails` | string[] | Yes | Emails to verify. |
| `name` | string | No | Task name; auto-generated if omitted. |
| `url` | string | No | Webhook URL - one event per verified email. Header: `event-type: bulk.email_verification_finished`. |
| `url_finished` | string | No | Webhook URL - one event when the whole task finishes. Header: `event-type: bulk.task_finished`. |
| `mode` | string | No | `regular` (default) or `deepverify`, applied to all emails. |
| `greylisting_bypass` | string | No | `auto` (default), `speed` (~1 min retry delay; small/time-sensitive lists; more `risky` flags), or `robust` (~5 min retry delay; large lists; fewer `risky` flags). |
| `disable_catchall_verify` | string | No | `0` (default) or `1`. When `1`, catch-all/SEG-protected emails return `unknown`, `score: -1`, cost 0 credits. |

### Example request

```bash
curl -X POST "https://api.bounceban.com/v1/verify/bulk" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["dev@bounceban.com", "support@bounceban.com"]}'
```

### Example response (200)

```json
{ "id": "6374973d2307debafb85a58d", "credits_remaining": 14973 }
```

---

## Create bulk task from a CSV file

```
POST https://api.bounceban.com/v1/verify/bulk/file
Content-Type: multipart/form-data
```

Max file size **25 MB**. The file may contain multiple columns; one column is used for emails. All original columns are preserved in exports.

### Form parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | Task name; defaults to the file name. |
| `email_column` | integer | No | Zero-based index of the email column. If omitted, auto-detected from the first 6 rows; an error is returned if emails are found in multiple columns. |
| `mode_column` | integer | No | Zero-based index of a column with per-email DeepVerify settings. Values `deepverify`, `yes`, `y`, `1`, `true` enable DeepVerify for that row. |
| `greylisting_bypass` | string | No | `auto` / `speed` / `robust` - same as above. |
| `url` | string | No | Per-email webhook. Header: `event-type: bulk.email_verification_finished`. |
| `url_finished` | string | No | Task-finished webhook. Header: `event-type: bulk.task_finished`. |
| `disable_catchall_verify` | string | No | `0` (default) or `1`. |
| `file` | binary | Yes | CSV file. **Must be the LAST field in the multipart form**, otherwise other fields (e.g. `url_finished`) may not work. |

### Example request

```bash
curl -X POST "https://api.bounceban.com/v1/verify/bulk/file" \
  -H "Authorization: YOUR_API_KEY" \
  -F "name=My import" \
  -F "email_column=0" \
  -F "file=@emails.csv"
```

### Example response (200)

```json
{ "id": "6374973d2307debafb85a58d", "credits_remaining": 14973 }
```

---

## Get bulk task status

```
GET https://api.bounceban.com/v1/verify/bulk/status?id=TASK_ID
```

### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Task ID. |
| `status` | string | `importing` -> `verifying` -> `finished`. |
| `total_count` | integer | Emails to verify (importing/verifying) or verified (finished). |
| `finished_count` | integer | Emails imported (importing) or verified (verifying). |
| `pushed_count` | integer | Webhook events delivered (if a webhook was set). |
| `deliverable_count` / `undeliverable_count` / `risky_count` / `unknown_count` / `catchall_count` | integer | Result counts; only when `finished`. |
| `credits_consumed` | float | Only when `finished`. |
| `credits_remaining` | float | Only when `finished`. `-1` means unlimited. |

### Example

```bash
curl "https://api.bounceban.com/v1/verify/bulk/status?id=6374973d2307debafb85a58d" \
  -H "Authorization: YOUR_API_KEY"
```

```json
{
  "id": "6374973d2307debafb85a58d",
  "status": "finished",
  "total_count": 2,
  "deliverable_count": 2,
  "undeliverable_count": 0,
  "risky_count": 0,
  "unknown_count": 0,
  "credits_consumed": 2.0,
  "credits_remaining": 14973.0
}
```

---

## Get results for specific emails

```
POST https://api.bounceban.com/v1/verify/bulk/emails
Content-Type: application/json
```

### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Bulk task ID. |
| `emails` | string[] | Yes | Up to **100** emails, all from this task. |

### Example

```bash
curl -X POST "https://api.bounceban.com/v1/verify/bulk/emails" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "6374973d2307debafb85a58d", "emails": ["dev@bounceban.com"]}'
```

```json
{
  "result": "ok",
  "items": [
    {
      "status": "success",
      "email": "dev@bounceban.com",
      "result": "deliverable",
      "score": 99,
      "is_disposable": false,
      "is_accept_all": false,
      "is_role": true,
      "is_free": false,
      "mx_records": ["alt1.aspmx.l.google.com", "aspmx.l.google.com"],
      "smtp_provider": "Google",
      "verify_at": "2022-11-16T07:54:37.480Z"
    }
  ]
}
```

`result` is `ok` on success, `err` if the task hasn't finished yet.

---

## Dump all results as JSON (paginated)

```
GET https://api.bounceban.com/v1/verify/bulk/dump?id=TASK_ID
```

Works even while the task is still running (omit `state` to get everything verified so far). Results available for 90 days.

### Parameters (query)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Bulk task ID. |
| `state` | string | No | Filter: `deliverable`, `risky`, `undeliverable`, `unknown`. Omit to get all verified emails, including in-progress tasks. |
| `cursor` | string | No | Pagination cursor from the previous response. |
| `page_size` | integer | No | 100-3000, default 100. |
| `retrieve_all` | string | No | Set `1` to fetch everything at once (only if the task has <= 20,000 emails; ignores `cursor` and `page_size`). |

### Pagination loop for agents

1. Request without `cursor`.
2. Read `items` and `cursor` from the response.
3. If `cursor` is non-null, request again with `cursor=<value>`.
4. Stop when `cursor` is null.

### Example

```bash
curl "https://api.bounceban.com/v1/verify/bulk/dump?id=6374973d2307debafb85a58d&page_size=100" \
  -H "Authorization: YOUR_API_KEY"
```

```json
{
  "result": "ok",
  "cursor": null,
  "items": [
    {
      "status": "success",
      "email": "dev@bounceban.com",
      "result": "deliverable",
      "score": 99,
      "is_disposable": false,
      "is_accept_all": false,
      "is_role": true,
      "is_free": false,
      "mx_records": ["alt1.aspmx.l.google.com", "aspmx.l.google.com"],
      "smtp_provider": "Google",
      "verify_at": "2022-11-16T07:54:37.480Z"
    }
  ]
}
```

---

## Export results to a CSV file

```
POST https://api.bounceban.com/v1/verify/bulk/export
Content-Type: application/json
```

Returns a public download link that **expires after 4 hours** (you can request a new one anytime within the 90-day retention window). Only works after the task has **finished**. Link generation may take time: ~30 s for 100k emails, ~2 min for 400k. If the link isn't ready, wait a few seconds and retry - max **15 requests per export per 15 minutes**.

### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Completed bulk task ID. |
| `keep_all_rows` | boolean | No | `true` keeps all source CSV rows (even without email). Only for tasks created via `/v1/verify/bulk/file`. Default `false`. |
| `criteria` | object | No | Filter which emails to export (see below). |

### `criteria` fields (all optional booleans unless noted)

| Field | Default | Description |
| --- | --- | --- |
| `deliverable` | `true` | Include deliverable emails. |
| `risky` | `false` | Include risky emails. |
| `risky_score` | `50` | Integer 0-100. Minimum score for risky emails; only if `risky` is `true`. |
| `undeliverable` | `false` | Include undeliverable emails. |
| `unknown` | `false` | Include unknown emails. |
| `free` | `true` | Include free-provider emails. |
| `role` | `true` | Include role emails. |
| `accept_all` | `true` | Include accept-all emails. |
| `disposable` | `false` | Include disposable emails. |

### Example

```bash
curl -X POST "https://api.bounceban.com/v1/verify/bulk/export" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "6374973d2307debafb85a58d", "criteria": {"deliverable": true, "risky": true, "risky_score": 70}}'
```

```json
{
  "result": "ok",
  "download_url": "https://bounceban.s3.us-west-2.amazonaws.com/export/bulk/laHkQ.csv?..."
}
```

---

## Delete a bulk task

```
POST https://api.bounceban.com/v1/verify/bulk/destroy
Content-Type: application/json
```

**Irreversible.** The task and all its data are removed immediately.

### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Bulk task ID. |

### Example

```bash
curl -X POST "https://api.bounceban.com/v1/verify/bulk/destroy" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "6374973d2307debafb85a58d"}'
```

```json
{ "result": "ok" }
```

---

## Error responses (all bulk endpoints)

| HTTP status | Meaning |
| --- | --- |
| `400` | Invalid parameter. |
| `401` | Authorization missing or invalid. |
| `403` | Insufficient credits (`credits_required`, `credits_remaining`, `message` in body). |
| `405` | Account blocked. |
| `429` | Rate limited. |
| `500` | Unexpected error. |

---

# Check API

Quickly check basic information about an email or domain **without SMTP verification**: domain type (work / free / disposable), username type (personal / role), and syntax validity. Useful for blocking disposable emails at sign-up or free emails on demo-request forms.

**Cost:** 1 credit per successful request from your **Check Plan** - a separate balance from verification credits. Check balances: https://bounceban.com/app/account/billing

## Endpoint

```
GET https://api.bounceban.com/v1/check
```

### Parameters (query)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | No* | Email to check. Takes precedence if both are provided. |
| `domain` | string | No* | Domain to check. |

*Provide at least one of `email` or `domain`.

### Example request

```bash
curl "https://api.bounceban.com/v1/check?email=sales@example.com" \
  -H "Authorization: YOUR_API_KEY"
```

### Example response (200)

```json
{
  "status": "success",
  "domain_type": "work",
  "username_type": "role",
  "syntax_valid": true,
  "credits_consumed": 1,
  "credits_remaining": 5
}
```

### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `status` | string | `success` or `error` (on `error`, try again). |
| `domain_type` | string | `work` (business domain), `free` (e.g. gmail.com), or `disposable` (e.g. 001xs.org). |
| `username_type` | string | `personal` (e.g. john@) or `role` (e.g. sales@). Only returned when an email was submitted. |
| `syntax_valid` | boolean | Whether the email syntax is valid (e.g. `k&32@example.com` -> `false`). |
| `credits_consumed` | float | Credits consumed. |
| `credits_remaining` | float | Check Plan credits remaining. `-1` means unlimited. |

### Error responses

| HTTP status | Meaning |
| --- | --- |
| `400` | Invalid parameter. |
| `401` | Authorization missing or invalid. |
| `403` | Insufficient credits. |
| `405` | Account blocked. |
| `429` | Rate limited. |
| `500` | Unexpected error. |

---

# Account API

Get account information: credits balance and per-endpoint rate limits.

## Endpoint

```
GET https://api.bounceban.com/v1/account
```

No parameters.

### Example request

```bash
curl "https://api.bounceban.com/v1/account" \
  -H "Authorization: YOUR_API_KEY"
```

### Example response (200)

```json
{
  "owner_email": "dev@bounceban.com",
  "available_credits": 375215,
  "rate_limit": [
    { "api": "/verify/single", "limit": "25 per second" },
    { "api": "/verify/single/status", "limit": "25 per second" },
    { "api": "/verify/bulk", "limit": "3 per second" },
    { "api": "/verify/bulk/status", "limit": "25 per second" },
    { "api": "/verify/bulk/export", "limit": "25 per second" },
    { "api": "/verify/bulk/dump", "limit": "25 per second" },
    { "api": "/account", "limit": "5 per second" }
  ]
}
```

### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `owner_email` | string | Account owner's email. |
| `available_credits` | float | Credits remaining. `-1` means unlimited (custom plans only). |
| `rate_limit` | array | Per-endpoint rate limits (`api`, `limit`). |

Need a higher rate limit? Fill out https://forms.gle/3De4UMZKpxPiPv5M8 or email dev@bounceban.com.

### Error responses

| HTTP status | Meaning |
| --- | --- |
| `401` | Authorization missing or invalid. |
| `405` | Account blocked. |
| `429` | Rate limited. |
| `500` | Unexpected error. |

---

# Webhooks

Receive verification results in real time via HTTP POST instead of polling. Set a webhook by passing a `url` (and/or `url_finished` for bulk tasks) parameter when creating a verification request.

## Delivery behavior

- Payloads are JSON, sent via HTTP POST.
- Every event includes an `event-type` header for routing.
- On delivery failure, the system retries up to **2 more times** within a short interval.
- For high volume, make sure your webhook server can handle the traffic. Tunneling tools like ngrok often fail under load; for testing try https://typedwebhook.tools/ instead (not affiliated).

## Event types

| `event-type` header | Trigger | Set via |
| --- | --- | --- |
| `single.email_verification_finished` | A single email verification finished | `url` on `/v1/verify/single` (standard or waterfall) |
| `bulk.email_verification_finished` | One email in a bulk task finished | `url` on `/v1/verify/bulk` or `/v1/verify/bulk/file` |
| `bulk.task_finished` | A whole bulk task finished | `url_finished` on `/v1/verify/bulk` or `/v1/verify/bulk/file` |

## Payload: `single.email_verification_finished`

A single JSON object:

```json
{
  "id": "502abcde",
  "status": "success",
  "email": "dev@bounceban.com",
  "result": "deliverable",
  "score": 99,
  "is_disposable": false,
  "is_accept_all": false,
  "is_role": true,
  "is_free": false,
  "mx_records": ["alt1.aspmx.l.google.com", "aspmx.l.google.com"],
  "smtp_provider": "Google",
  "mode": "regular",
  "verify_at": "2022-11-16T07:21:24.943Z",
  "credits_consumed": 1.0,
  "credits_remaining": 375214.0
}
```

## Payload: `bulk.email_verification_finished`

A JSON **array** (one event per verified email):

```json
[
  {
    "task_id": "68b167c5d10abc82d391f13f",
    "status": "success",
    "email": "dev@bounceban.com",
    "result": "deliverable",
    "score": 99,
    "is_disposable": false,
    "is_accept_all": false,
    "is_role": true,
    "is_free": false,
    "mx_records": ["alt1.aspmx.l.google.com", "aspmx.l.google.com"],
    "smtp_provider": "Google",
    "verify_at": "2022-11-16T07:21:24.943Z"
  }
]
```

## Payload: `bulk.task_finished`

```json
{
  "id": "68b167c5d10abc82d391f13f",
  "status": "finished",
  "total_count": 2,
  "pushed_count": 2,
  "deliverable_count": 0,
  "risky_count": 2,
  "undeliverable_count": 0,
  "unknown_count": 0,
  "catchall_count": 2,
  "credits_consumed": 2.0,
  "credits_remaining": 1483505.176
}
```