Stopping a Running Bulk Verification Task

You can stop a bulk verification task while it is running, in the web app or with the API. Results that are already verified are kept, and you are not charged for any email that doesn't get a result.

What happens when you stop a task

• Emails that haven't been sent for verification yet are not verified.
• Emails that are already being verified get up to about 60 seconds to finish. Any email still without a result after that is given up, and its result is not returned later (not in the web app, the API or webhooks).
• The task finishes as soon as all of those emails finish, or when the 60 seconds are up, whichever comes first.
• When the task finishes, the credits for every email without a result are refunded automatically.
• A task that is still queued and hasn't started verifying stops right away, and all of its credits are refunded.

You can stop only your own tasks that are queued or verifying. A task that is still importing or has already finished can't be stopped.

Stop a task in the web app

1. Go to Bulk Verification: https://bounceban.com/app/bulk/list.
2. Hover over the task that is verifying and click Halt verification.
3. Confirm.

While the task is stopping, it shows Stopping. You can't export or delete it yet. This usually takes no more than about a minute.

When the task has stopped, it shows its final results. You can then:

• Export the results of the emails that were verified.
• Hover over the task and click Resume verification to verify the remaining emails. Credits are charged for them as usual.
• Delete the task.

Stop a task with the API

POST https://api.bounceban.com/v1/verify/bulk/stop

Send your API key in the Authorization header and the task ID in a JSON body:

• id (string, required): the bulk task ID.

Example request:

curl -X POST "https://api.bounceban.com/v1/verify/bulk/stop" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "6374973d2307debafb85a58d"}'

Example response (200):

{
  "result": "ok",
  "id": "6374973d2307debafb85a58d",
  "status": "verifying",
  "stopped": true,
  "msg": "The task is being stopped. Emails not yet submitted will not be verified, and emails still being verified will be given up to 60 seconds to finish. Credits for all unverified emails will be refunded when the task finishes."
}

• status is verifying while the task is stopping and finished once it has stopped. A queued task returns finished right away.
• stopped is always true when the request succeeds.
• Calling stop again on a task that is stopping or already stopped is safe. It returns 200 with "result": "ok".
• A 400 error is returned if the ID is invalid, or if the task can't be stopped (for example, it is still importing or has already finished).

Check when a stopped task has finished

Poll GET https://api.bounceban.com/v1/verify/bulk/status?id=TASK_ID until status is finished:

• Stopping: "status": "verifying" and "stopped": true.
• Stopped: "status": "finished" and "stopped": true, plus not_verified_count, the number of emails that got no result (not sent for verification, or given up). These emails are not charged.

Example response for a stopped task:

{
  "id": "6374973d2307debafb85a58d",
  "status": "finished",
  "stopped": true,
  "not_verified_count": 120,
  "total_count": 380,
  "deliverable_count": 310,
  "undeliverable_count": 50,
  "risky_count": 20,
  "unknown_count": 0,
  "credits_consumed": 380.0,
  "credits_remaining": 14620.0
}

Results, exports and webhooks for a stopped task

• Export (POST /v1/verify/bulk/export) works only after the task has finished. While it is stopping, the request returns "result": "error" with a message that the task has not finished yet.
• Dump (GET /v1/verify/bulk/dump) returns only emails that have a result.
• Get results for specific emails (POST /v1/verify/bulk/emails) returns emails that got no result with "status": "canceled". They are not charged.
• The task-finished webhook (url_finished) is sent when the stopped task finishes. Its status is still finished, and it also includes "stopped": true and not_verified_count.
• The per-email webhook (url) is not sent for emails that were not verified or were given up.

Full API reference: https://bounceban.com/public/doc/api.html