> ## Documentation Index
> Fetch the complete documentation index at: https://deepline.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Bounceban Get Bulk Status: Inputs, Cost & CLI Example

> Read, export, or manage an existing BounceBan bulk verification task. Includes inputs, outputs, costs, and Deepline CLI examples for GTM automation.

## Run in Enrichment Spreadsheet

<Info>
  Use this function as a column step in `deepline enrich`.
</Info>

```bash theme={null}
deepline enrich --input leads.csv --output leads.enriched.csv --with 'result=bounceban_get_bulk_status:{"id":"{{id}}"}' --json
```

<Tip>
  Map payload values to spreadsheet columns with `{{column_name}}` placeholders.
</Tip>

## Input Schema

| Name         | Type     | Required | Default | Description                      |
| ------------ | -------- | -------- | ------- | -------------------------------- |
| `payload.id` | `string` | Yes      |         | Bulk email verification task id. |

<details>
  <summary>Show raw input schema</summary>

  ### Input JSON Schema

  ```json theme={null}
  {
    "type": "object",
    "description": "You can use this API to get the latest progress and stats for a bulk email verification task using a task ID.",
    "properties": {
      "id": {
        "type": "string",
        "description": "Bulk email verification task id."
      }
    },
    "required": [
      "id"
    ],
    "additionalProperties": false
  }
  ```
</details>

## Output Schema

| Name          | Type     | Required | Default | Description                                    |
| ------------- | -------- | -------- | ------- | ---------------------------------------------- |
| `result.data` | `object` | Yes      |         | Provider response payload.                     |
| `result.meta` | `object` | No       |         | Additional response metadata (status, paging). |

<details>
  <summary>Show raw output schema</summary>

  ### Output JSON Schema

  ```json theme={null}
  {
    "type": "object",
    "description": "Standard tool result payload.",
    "properties": {
      "data": {
        "type": "object",
        "description": "Provider response payload.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Bulk email verification task id."
          },
          "status": {
            "type": "string",
            "description": "Bulk email verification task status. > `importing` indicates the list of emails are being imported for verification. > `verifying` indicates all the emails are imported and are being verified. > `finished` indicates verification for the whole list has finished.",
            "enum": [
              "importing",
              "verifying",
              "finished"
            ]
          },
          "total_count": {
            "type": "integer",
            "description": "If `status` is `importing` or `verifying`, it represents the number of emails for verification; If `status` is `finished`, it represents the number of emails verified."
          },
          "finished_count": {
            "type": "integer",
            "description": "It represents the number of emails imported when `status` is `importing`, and the number of emails verified when `status` is `verifying`."
          },
          "pushed_count": {
            "type": "integer",
            "description": "It represents the number of emails pushed via webhook events. Only returned when `status` is `verifying` or `finished`, and a webhook was submitted when creating the bulk verification task."
          },
          "deliverable_count": {
            "type": "integer",
            "description": "It represents the number of emails that are `deliverable`. Only returned when `status` is `finished`."
          },
          "undeliverable_count": {
            "type": "integer",
            "description": "It represents the number of emails that are `undeliverable`. Only returned when `status` is `finished`."
          },
          "risky_count": {
            "type": "integer",
            "description": "It represents the number of emails that are `risky`. Only returned when `status` is `finished`."
          },
          "unknown_count": {
            "type": "integer",
            "description": "It represents the number of emails that are `unknown`. Only returned when `status` is `finished`."
          },
          "catchall_count": {
            "type": "integer",
            "description": "It represents the number of emails that are `catchall`. Only returned when `status` is `finished`."
          }
        },
        "additionalProperties": false
      },
      "meta": {
        "type": "object",
        "description": "Additional response metadata (status, paging).",
        "additionalProperties": true
      }
    },
    "required": [
      "data"
    ],
    "additionalProperties": false
  }
  ```
</details>

## Advanced: Direct CLI

<Info>
  Use direct execution for single payload debugging.
</Info>

```bash theme={null}
deepline tools execute bounceban_get_bulk_status --payload '{
  "id": "string"
}' --json
```

### CLI flags

| Flag                        | Description                                         |
| --------------------------- | --------------------------------------------------- |
| `--json`                    | Print machine-readable output.                      |
| `--wait`                    | Wait for terminal provider status when supported.   |
| `--debug`                   | Enable wait mode with additional status/log output. |
| `--wait-timeout SECONDS`    | Max seconds to wait in wait mode.                   |
| `--poll-interval SECONDS`   | Polling interval in seconds during wait mode.       |
| `--timeout SECONDS`         | Request timeout in seconds.                         |
| `--connect-timeout SECONDS` | Connection timeout in seconds.                      |

## Provider API Context

<details>
  <summary>Show provider reference (optional)</summary>

  ```md theme={null}
  Sources reviewed 2026-07-26:

  - https://bounceban.com/public/doc/api.yaml
  - https://bounceban.com/public/doc/llms.txt

  ## Auth

  BounceBan expects the managed API key in the `Authorization` header, without a Bearer prefix.

  ## Pricing

  - Single verification and each successfully verified email in a bulk task consume one BounceBan verification credit.
  - The normal single verification response and completed bulk-status response expose `credits_consumed`; this is the preferred settlement input.
  - A basic single verification with `disable_catchall_verify=1` can return `unknown` with zero verification cost.
  - Single and bulk result polling, result retrieval, exports, task deletion, and account lookup do not consume verification credits.
  - The configured managed-account provider exchange rate is $0.004 per BounceBan credit, as directed for this integration.

  ## Endpoint notes

  The standard single verification call can return `status: verifying`; poll the free single-status endpoint with its id rather than submitting the email again. The waterfall endpoint can return HTTP 408 while retaining the verification task; BounceBan documents retries for the same email within 30 minutes as free.

  The bulk file upload is documented as `multipart/form-data`. It remains registered but disabled until the shared V2 runtime gains multipart transport, so it cannot silently send malformed JSON. The waterfall endpoint is also disabled: its HTTP 408 can retain a billable task, which requires a non-2xx async settlement path before it can be exposed safely.

  ## Response evidence

  `raw-upstream-examples/single-success.json` preserves the provider's documented single-verification response, including `credits_consumed`. `raw-upstream-examples/bulk-status-finished.json` preserves the completed bulk-status response and its task-level `credits_consumed`. Normalized Deepline samples are stored separately under `sample-outputs/`.
  ```
</details>

## Cost

* Pricing model: `fixed` (per call).
* Estimated Deepline credits: `0` per pricing unit.
* Provider-native pricing may still exist outside Deepline credit billing.
* Billing mode: `no_bill`.