> ## 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 Single Status: Inputs, Cost & CLI Example
> Inspect BounceBan account credits and rate limits. Includes inputs, outputs, pricing notes, Deepline CLI examples, and GTM automation guidance.
## Run in Enrichment Spreadsheet
Use this function as a column step in `deepline enrich`.
```bash theme={null}
deepline enrich --input leads.csv --output leads.enriched.csv --with 'result=bounceban_get_single_status:{"id":"{{id}}"}' --json
```
Map payload values to spreadsheet columns with `{{column_name}}` placeholders.
## Input Schema
| Name | Type | Required | Default | Description |
| ------------ | -------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payload.id` | `string` | Yes | | The unique id returned by every successful request to the [/v1/verify/single](#tag/Single-verification/paths/~1v1~1verify~1single/get) endpoint. > Please consider implementing rate limiting for polling requests to avoid excessive traffic. We recommend capping polling to no more than 10 requests for the same verification `id` within a 5-minute period. After 5 minutes, polling should stop if no results are available, and a new verification request should be initiated instead. > For a more efficient approach, we highly recommend using a webhook event to listen for verification results. You can set this up by providing a callback URL via the `url` parameter in your [/verify/single](#tag/Single-verification/paths/~1v1~1verify~1single/get) API request, allowing results to be sent to your system without the need for repeated polling. |
Show raw input schema
### Input JSON Schema
```json theme={null}
{
"type": "object",
"description": "Get the verification result for single email verification. Requests to this endpoint don’t cost verification credits. The result will be available for 90 days after verification.",
"properties": {
"id": {
"type": "string",
"description": "The unique id returned by every successful request to the [/v1/verify/single](#tag/Single-verification/paths/~1v1~1verify~1single/get) endpoint. > Please consider implementing rate limiting for polling requests to avoid excessive traffic. We recommend capping polling to no more than 10 requests for the same verification `id` within a 5-minute period. After 5 minutes, polling should stop if no results are available, and a new verification request should be initiated instead. > For a more efficient approach, we highly recommend using a webhook event to listen for verification results. You can set this up by providing a callback URL via the `url` parameter in your [/verify/single](#tag/Single-verification/paths/~1v1~1verify~1single/get) API request, allowing results to be sent to your system without the need for repeated polling."
}
},
"required": [
"id"
],
"additionalProperties": false
}
```
## Output Schema
| Name | Type | Required | Default | Description |
| ------------- | -------- | -------- | ------- | ---------------------------------------------- |
| `result.data` | `object` | Yes | | Verification result for this task. |
| `result.meta` | `object` | No | | Additional response metadata (status, paging). |
Show raw output schema
### Output JSON Schema
```json theme={null}
{
"type": "object",
"description": "Standard tool result payload.",
"properties": {
"data": {
"type": "object",
"description": "Verification result for this task.",
"properties": {
"id": {
"type": "string",
"description": "Unique ID for this single verification task. This parameter is returned for all status values. If verification result is not available for a request in 15 seconds, the response for this endpoint will not include other verification information (e.g. score, deliverable or not deliverable, etc.) and you should use this ID to poll for the verification result via the [/single/status](#tag/Single-verification/paths/~1v1~1verify~1single~1status/get) endpoint, if you don’t want to receive it through webhook events by setting a target URL with the url parameter. The ID is valid for 90 days, however, exercise caution when relying on verification results after an extended period, for example, 2 weeks."
},
"status": {
"type": "string",
"description": "Verification status for this task. > `success` Indicates the task is finished and the final verification result can be returned. > `verifying` Indicates that the email is still undergoing verification. A small percentage of emails, particularly those using greylisting technologies, may not return verification results in real time. In such cases, please poll for the verification results using the [/single/status](#tag/Single-verification/paths/~1v1~1verify~1single~1status/get) API with the provided `id`. Alternatively, you can receive the results via a webhook by specifying a target URL with the `url` parameter. Please DO NOT send the same requests repeatedly as each request will cost 1 credit . > `queue` Indicates that the rate limit for your account is reached and the email is queued for verification. In such cases, please poll for the verification results using the [/single/status](#tag/Single-verification/paths/~1v1~1verify~1single~1status/get) API with the provided `id`. Alternatively, you can receive the results via a webhook by specifying a target URL with the `url` parameter. Please DO NOT send the same requests repeatedly as each request will cost 1 credit .",
"enum": [
"success",
"verifying",
"queue"
]
},
"try_again_at": {
"type": "integer",
"description": "The recommended Unix timestamp to poll the [/single/status](#tag/Single-verification/paths/~1v1~1verify~1single~1status/get) endpoint for an updated verification result. This value is only returned when the verification status is `verifying`."
},
"email": {
"type": "string",
"description": "The email address submitted for verification."
},
"result": {
"type": "string",
"description": "The state (verification result) for the email.",
"enum": [
"deliverable",
"risky",
"undeliverable",
"unknown"
]
},
"score": {
"type": "integer",
"description": "The score (0 ~ 100) represents the deliverability of an email - the higher, the better.",
"minimum": 0,
"maximum": 100
},
"is_disposable": {
"type": "boolean",
"description": "Whether the email is disposable."
},
"is_accept_all": {
"type": "boolean",
"description": "Whether the email is accept-all."
},
"is_role": {
"type": "boolean",
"description": "Whether the email is role based."
},
"is_free": {
"type": "boolean",
"description": "Whether the email is a free email."
},
"mx_records": {
"type": "array",
"description": "All MX records for the email.",
"items": {
"type": "string"
}
},
"smtp_provider": {
"type": "string",
"description": "SMTP provider based on the main MX record, e.g. if the MX record for an email is `alt1.aspmx.l.google.com`, then the smtp provider will be `Google`. Currently a value is only returned if the MX records are notable."
},
"mode": {
"type": "string",
"description": "Verification mode."
},
"verify_at": {
"type": "string",
"description": "The time the verification task finished.",
"format": "date-time"
}
},
"additionalProperties": false
},
"meta": {
"type": "object",
"description": "Additional response metadata (status, paging).",
"additionalProperties": true
}
},
"required": [
"data"
],
"additionalProperties": false
}
```
## Advanced: Direct CLI
Use direct execution for single payload debugging.
```bash theme={null}
deepline tools execute bounceban_get_single_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
Show provider reference (optional)
```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/`.
```
## 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`.