Single email verification (Clay, N8N, and other waterfall services)
This API is recommended for Clay, N8N, and any other services that use one single HTTP request for email verification). Note: This endpoint uses a different base URL than other BounceBan APIs. The full URL for this API is https://api-waterfall.bounceban.com/v1/verify/single.<br><br>
With this API, you don't need to send a seperate api (/v1/verify/single/status) call to poll for verification result. Instead you just send the same request again if it times out. The API times out with status code 408 if verification is not completed within the specified timeout period (default 80 seconds, configurable via the timeout parameter). In this case, you should send the same request again - retries within 30 mins of the initial verification request for the same email won't deduct credits.<br><br> The 408 response always includes the verification id, and verification continues in the background - so alternatively you can fetch the finished result later at no charge via /v1/verify/single/status, which is available on this waterfall base URL as well. Note that /v1/verify/single and /v1/verify/single/status are the only endpoints served on api-waterfall.bounceban.com. ?email= always (re)submits the email for verification - it never looks up a past result: within 30 minutes of the initial request, resending the same request is free and returns the same verification; after that window, it starts a new, billed verification. To look up an existing result without any risk of a new charge (at any time within 90 days), use ?id= with the status endpoint instead.<br><br> Tutorials for popular automation services: <br> Clay （native integration): <br> https://support.bounceban.com/article/how-to-use-bounceban-with-clay<br> n8n (native integration): <br> https://support.bounceban.com/article/how-to-use-the-n8n-node<br>
Request
- Base URL: https://api-waterfall.bounceban.com
- URL: https://api-waterfall.bounceban.com/v1/verify/single (for waterfall)
- Auth: API key in header Authorization
Query parameters
The email that needs to get verified.
(Optional) Setting the verification mode for the verification job. Default mode is regular.<br>
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.<br> 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
(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/ 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.<br><br> Please note that the webhook event payload will be in JSON format.
{
"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",
"alt2.aspmx.l.google.com",
"alt3.aspmx.l.google.com",
"alt4.aspmx.l.google.com",
"aspmx.l.google.com"
],
"smtp_provider": "Google",
"mode": "regular",
"verify_at": "2022-11-16T07:21:24.943Z",
"credits_consumed": 1.000,
"credits_remaining": 375214.000
}
(Optional) The timeout duration in seconds for the verification request. The API will return a 408 timeout status code if verification is not completed within this timeframe. Default is 80 seconds.<br><br> Important: Make sure the timeout value is set to no bigger than the maximum period your service allows. For example, if your service has a 120-second timeout limit, do not set this parameter to more than 120 seconds.
(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.
Response
ok
Changes
No recorded changes to this operation across all 1 revision of this API.