> ## 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: Verify Single

> Verify (validate) one email address before sending, including catch-all domains. Includes inputs, outputs, SDK V2 examples, and Deepline cost.

Verify (validate) one email address before sending, including catch-all domains.

> [!NOTE]
>
> Tool ID: `bounceban_verify_single`

## Run this action

Use the TypeScript SDK for one call. Use `ctx.tools.execute(...)` inside a Play for durable calls, scheduled calls, or CSV processing.

```ts theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
import { Deepline } from 'deepline';

const deepline = await Deepline.connect();
const result = await deepline.tools.execute(
  'bounceban_verify_single',
  {
    "email": "jane.doe@example.com"
  },
);

console.log(result.toolResponse.raw);
```

### CLI

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline tools execute bounceban_verify_single --input '{
  "email": "jane.doe@example.com"
}' --json
```

## Example response

The SDK returns this shape at `result.toolResponse.raw`. The example values illustrate the response.

```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
{
  "data": {
    "id": "id_123",
    "status": "success",
    "try_again_at": 123
  }
}
```

Use `deepline describe bounceban_verify_single --json` for the latest machine-readable contract.

## Input reference

**Overview:** This endpoint is designed for advanced users requiring granular control over BounceBan server connections. **Timeout & Async Handling:** This request has a **15-second timeout**. If verification completes within this window, the result is returned immediately. If verification exceeds 15 seconds, the API returns a `200 OK` response containing a transaction `id` and the status `verifying`. You can retrieve the final result in two ways: \* **Polling:** Use the returned `id` to query the [`v1/verify/single/status`](#tag/Single-verification/paths/~1v1~1verify~1single~1status/get) endpoint. \* **Webhook:** specific a `url` parameter in your initial request to receive the result via webhook. **Alternative for Long Connections:** If your infrastructure supports long-held GET connections (e.g., Clay, n8n), we recommend using the **Waterfall API** instead to receive results in a single See the live schema below for the complete notes.

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `payload.email` | `string` | Yes | — | The email that needs to get verified. |
| `payload.mode` | `"regular" \| "deepverify"` | No | — | (Optional) Setting the verification mode for the verification job. Default mode is `regular`. > `regular`: The default option for email verification. It does not assume that the domain of the email owner's current company website matches the domain of the email being verified. > `deepverify`: DeepVerify operates on the assumption that the domain of the email owner's current company website matches the domain of the email being verified. This assumption can improve the success rate of verifying See the live schema for the complete constraint. |
| `payload.url` | `string` | No | — | (Optional) A webhook target URL specified to receive verification result event in real-time through an HTTP POST request. In case of a failed webhook event delivery, the system will attempt to resend the event up to two additional times within a short interval. For those verifying a substantial volume of emails, it's crucial to ensure that your webhook server is equipped to manage the incoming traffic. Services such as ngrok have been known to encounter issues when dealing with a significant See the live schema for the complete constraint. |
| `payload.disable_catchall_verify` | `"0" \| "1"` | No | — | (Optional) Defaults to `0`. When set to `1`, BounceBan performs only basic SMTP verification. This may leave catch-all emails or those protected by ESGs (Email Security Gateways) unverified. For these addresses, the API will return `result: 'unknown'`, `score: -1`, and the credit cost is 0. Allowed: `0`, `1`. |

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

  ### Input JSON Schema

  ````json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
  {
    "type": "object",
    "description": "**Overview:** This endpoint is designed for advanced users requiring granular control over BounceBan server connections. **Timeout & Async Handling:** This request has a **15-second timeout**. If verification completes within this window, the result is returned immediately. If verification exceeds 15 seconds, the API returns a `200 OK` response containing a transaction `id` and the status `verifying`. You can retrieve the final result in two ways: * **Polling:** Use the returned `id` to query the [`v1/verify/single/status`](#tag/Single-verification/paths/~1v1~1verify~1single~1status/get) endpoint. * **Webhook:** specific a `url` parameter in your initial request to receive the result via webhook. **Alternative for Long Connections:** If your infrastructure supports long-held GET connections (e.g., Clay, n8n), we recommend using the **Waterfall API** instead to receive results in a single synchronous request: [`https://api-waterfall.bounceban.com/v1/verify/single`](#tag/Single-verification/paths/~1v1~1verify~1single%20(for%20waterfall)/get) **Pricing:** * **Custom:** Custom rates apply for users on custom plans.",
    "properties": {
      "email": {
        "type": "string",
        "description": "The email that needs to get verified."
      },
      "mode": {
        "type": "string",
        "description": "(Optional) Setting the verification mode for the verification job. Default mode is `regular`. > `regular`: The default option for email verification. It does not assume that the domain of the email owner's current company website matches the domain of the email being verified. > `deepverify`: DeepVerify operates on the assumption that the domain of the email owner's current company website matches the domain of the email being verified. This assumption can improve the success rate of verifying accept-all emails. However, it is crucial to obtain the domain for the email owner's current company website from a reliable source, such as the email owner's LinkedIn profile or another trustworthy sales prospecting database. Learn more: [https://support.bounceban.com/article/what-is-deepverify](https://support.bounceban.com/article/what-is-deepverify)",
        "enum": [
          "regular",
          "deepverify"
        ]
      },
      "url": {
        "type": "string",
        "description": "(Optional) A webhook target URL specified to receive verification result event in real-time through an HTTP POST request. In case of a failed webhook event delivery, the system will attempt to resend the event up to two additional times within a short interval. For those verifying a substantial volume of emails, it's crucial to ensure that your webhook server is equipped to manage the incoming traffic. Services such as ngrok have been known to encounter issues when dealing with a significant number of events due to inherent limitations. We suggest exploring alternative testing services like TypedWebhook Tools [https://typedwebhook.tools/](https://typedwebhook.tools/) for a more robust solution. Please note that we are not affiliated with this service. > The webhook event will also include the `event-type: single.email_verification_finished` header so you can differentiate between different events. > Please note that the webhook event payload will be in JSON format. ``` { \"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\", \"alt2.aspmx.l.google.com\", \"alt3.aspmx.l.google.com\", \"alt4.aspmx.l.google.com\", \"aspmx.l.google.com\" ], \"smtp_provider\": \"Google\", \"verify_at\": \"2022-11-16T07:21:24.943Z\", \"credits_consumed\": 1.000, \"credits_remaining\": 375214.000 } ```"
      },
      "disable_catchall_verify": {
        "type": "string",
        "description": "(Optional) Defaults to `0`. When set to `1`, BounceBan performs only basic SMTP verification. This may leave catch-all emails or those protected by ESGs (Email Security Gateways) unverified. For these addresses, the API will return `result: 'unknown'`, `score: -1`, and the credit cost is 0.",
        "enum": [
          "0",
          "1"
        ]
      }
    },
    "required": [
      "email"
    ],
    "additionalProperties": false
  }
  ````
</details>

## Output reference

Standard tool result payload.

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `result.data` | `object` | Yes | — | Verification result for this task. |
| `result.data.id` | `string` | No | — | 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 See the live schema for the complete constraint. |
| `result.data.status` | `"success" \| "verifying" \| "queue"` | No | — | 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 See the live schema for the complete constraint. |
| `result.data.try_again_at` | `integer` | No | — | 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`. |
| `result.data.email` | `string` | No | — | The email address submitted for verification. |
| `result.data.result` | `"deliverable" \| "risky" \| "undeliverable" \| "unknown"` | No | — | The state (verification result) for the email. Allowed: `deliverable`, `risky`, `undeliverable`, `unknown`. |
| `result.data.score` | `integer` | No | — | The score (0 \~ 100) represents the deliverability of an email - the higher, the better. Minimum: 0. Maximum: 100. |
| `result.data.is_disposable` | `boolean` | No | — | Whether the email is disposable. |
| `result.data.is_accept_all` | `boolean` | No | — | Whether the email is accept-all. |
| `result.data.is_role` | `boolean` | No | — | Whether the email is role based. |
| `result.data.is_free` | `boolean` | No | — | Whether the email is a free email. |
| `result.data.mx_records` | `array` | No | — | All MX records for the email. |
| `result.data.smtp_provider` | `string` | No | — | 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. |
| `result.data.mode` | `string` | No | — | Verification mode. |
| `result.data.verify_at` | `string` | No | — | The time the verification task finished. Format: `date-time`. |
| `result.meta` | `object` | No | — | Additional response metadata (status, paging). |

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

  ### Output JSON Schema

  ```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
  {
    "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
  }
  ```
</details>

## Deepline cost

* Pricing model: `per_result` (per result).
* Estimated Deepline credits: `0.06` per pricing unit.

## Related documentation

* [BounceBan provider guide](https://deepline.com/docs/providers/bounceban/guide.md)
* [SDK V2 quickstart](https://deepline.com/docs/sdk-v2/quickstart.md)
* [SDK reference](https://deepline.com/docs/sdk-v2/sdk-reference.md)
* [Run tools across a CSV](https://deepline.com/docs/sdk-v2/batch-csv.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.