API

Send your key as Authorization: Bearer vk_... (or X-API-Key: vk_...). Make keys on the API keys page. Up to 20 requests a second per key. Every check costs one credit, except Unknowns, which are free.

Verdicts

result is one of the four verdicts. verdict and reason give the detail behind it.

Valid

The mailbox exists. send_safe is true.

Risky

Catch-all domain (verdict: catch_all), throwaway service (disposable) or role address (valid with role: true).

Invalid

Will bounce. reason is syntax, no_domain, no_mx, no_mailbox, mailbox_disabled, mailbox_full or rejected.

Unknown

The mail server didn't give a clear answer. Free. If retry_after is set (seconds), the server asked us to come back later: call again after that long.

One address: POST /api/v1/verify

curl -s https://app.bouncewarden.com/api/v1/verify \
  -H "Authorization: Bearer $BOUNCEWARDEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "dana.okafor@northwind.example"}'

Answers in a few seconds, or at once for an address checked recently. The reply includes result, verdict, reason, send_safe, role, provider, mx_host and the mail server's reply.

In Clay: add an HTTP API column, method POST, this URL, header Authorization set to Bearer and your key, body {"email": "/Email"} with the email column inserted. Map result into a column.

A list: POST /api/v1/jobs

curl -s https://app.bouncewarden.com/api/v1/jobs \
  -H "Authorization: Bearer $BOUNCEWARDEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["a@northwind.example", "b@fernpoint.example"],
       "webhook_url": "https://your-n8n.example/webhook/abc"}'

Returns {"job_id": ...} and reserves one credit per unique address; Unknowns come back when it finishes. Poll GET /api/v1/jobs/<job_id> or wait for the webhook. Up to 100,000 addresses per call; upload a CSV in the app for bigger lists.

When the list finishes, the webhook gets a POST with job_id, counts and results_url. Its X-Verifier-Signature: sha256=... header is an HMAC-SHA256 of the body, keyed with the key's webhook signing secret.

curl -s "https://app.bouncewarden.com/api/v1/jobs/JOB_ID/results?format=csv&send_safe=1" \
  -H "Authorization: Bearer $BOUNCEWARDEN_KEY"

In n8n: an HTTP Request node starts the list, a Webhook node catches the finish, and another HTTP Request node fetches results_url (JSON, or format=csv).

Credits: GET /api/v1/usage

Your credit balance (credits) and how many single checks this key's account made today, Unknowns included (checks_today).

Errors

401 bad or missing key. 402 not enough credits. 429 too many requests. Each comes with error and detail.