Single verification

Get single email verification result

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.<br><br> This endpoint is available on both base URLs - https://api.bounceban.com and https://api-waterfall.bounceban.com - with identical behavior, so waterfall integrations can look up past results without switching hosts.

get/v1/verify/single/status

Request

  • Base URL: https://api.bounceban.com
  • URL: https://api.bounceban.com/v1/verify/single/status
  • Auth: API key in header Authorization

Query parameters

idstring required

The unique id returned by every successful request to the /v1/verify/single endpoint (standard or waterfall, including the id in a waterfall 408 timeout response). The same value appears as Task ID in the Credits Usage export (https://bounceban.com/app/account/credits/usage) for Single (API) rows.

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.<br> <br> 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 API request, allowing results to be sent to your system without the need for repeated polling.

Response

Ok

idstring

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 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'success' | 'verifying' | 'queue'

Verification status for this task.

success Indicates the task is finished and the final verification result can be returned.<br><br> 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 API with the provided id. Alternatively, you can receive the results via a webhook by specifying a target URL with the url parameter. <span style="color:red;font-weight:bold">Please DO NOT send the same requests repeatedly as each request will cost 1 credit</span>.<br><br> 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 API with the provided id. Alternatively, you can receive the results via a webhook by specifying a target URL with the url parameter. <span style="color:red;font-weight:bold">Please DO NOT send the same requests repeatedly as each request will cost 1 credit</span>.

try_again_atinteger

The recommended Unix timestamp to poll the /single/status endpoint for an updated verification result. This value is only returned when the verification status is verifying.

emailstring

The email address submitted for verification.

result'deliverable' | 'risky' | 'undeliverable' | 'unknown'

The state (verification result) for the email.

scoreinteger

The score (0 ~ 100) represents the deliverability of an email - the higher, the better.

is_disposableboolean

Whether the email is disposable.

is_accept_allboolean

Whether the email is accept-all.

is_roleboolean

Whether the email is role based.

is_freeboolean

Whether the email is a free email.

mx_recordsstring[]

All MX records for the email.

smtp_providerstring

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.

modestring

Verification mode.

verify_atunknown
credits_consumednumber float

Credits consumed for this task.

credits_remainingnumber float

Credits remaining in your account after the current task. -1 means unlimited. Only returned for some custom plans.

Changes

No recorded changes to this operation across all 1 revision of this API.