Verify emails from your backend.

Base URL

https://bouncyboobs.dev

Authentication

Pass your key in the Authorization header. Keys start with bb_live_ and are shown in plaintext exactly once when created.

Authorization: Bearer bb_live_xxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Revoked keys return 401. Unknown keys return 401. Valid keys on a lapsed subscription return 402.

POST /api/verify

Run one email through the full pipeline and get a verdict back. Send a list to verify many at once (up to 1,000 per request).

curl https://bouncyboobs.dev/api/verify \
  -H "Authorization: Bearer $BOUNCYBOOBS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["alice@example.com"]}'

Response

{
  "results": [
    {
      "email": "alice@example.com",
      "verdict": "deliverable",
      "reason": "Mailbox exists and domain is healthy",
      "syntax_ok": true,
      "dns_ok": true,
      "disposable": false,
      "role_based": false,
      "smtp_ok": true,
      "suggestion": null,
      "checked_at": "2026-04-16T19:12:04Z"
    }
  ],
  "summary": {
    "total": 1,
    "deliverable": 1,
    "undeliverable": 0,
    "risky": 0,
    "unknown": 0
  },
  "quota": {
    "thresholdsCrossed": { "eighty": false, "hundred": false }
  }
}

Verdicts

• deliverable — active mailbox on a healthy domain.
• risky — role address, catch-all, or provider with mixed deliverability.
• undeliverable — typo, dead domain, disposable provider, or the mailbox does not exist.
• unknown — the receiving server refused to confirm (greylisting, rate-limited, transient error).

Status codes

• 200 — success. Inspect summary and results.
• 400 — malformed body or invalid email format.
• 401 — missing, unknown, or revoked API key.
• 402 — no active subscription, or monthly quota exhausted. Response body includes remaining and monthlyQuota.
• 413 — too many emails (cap is 1,000 per request).
• 429 — per-IP rate-limit. Retry after Retry-After seconds.

Webhooks

When a bulk job submitted via the dashboard finishes, we POST a signed event to your configured URL.

POST <your-url>
Content-Type: application/json
x-bouncyboobs-event: bulk_job.completed
x-bouncyboobs-signature: sha256=<hex>

{
  "type": "bulk_job.completed",
  "created_at": "2026-04-16T19:14:22Z",
  "data": {
    "job_id": "a77faa30-7046-4275-a09e-6e19f8827410",
    "label": "Q2 newsletter",
    "total": 4217,
    "deliverable": 3984,
    "undeliverable": 122,
    "risky": 71,
    "unknown": 40
  }
}

Verifying the signature (Node.js)

import crypto from "node:crypto";

export function verify(req, rawBody, secret) {
  const sig = req.headers["x-bouncyboobs-signature"] ?? "";
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(sig),
    Buffer.from(expected),
  );
}

We send one delivery attempt with a 5-second timeout. No retries yet — you can rely on the parallel email notification as a fallback while webhooks settle.

Rate limits & quotas

• Per-IP: 30 requests per hour for anonymous, 600 per hour for authenticated.
• Per-request: 1,000 emails (single-request cap). Larger lists — use the dashboard bulk uploader.
• Quota: every verification counts as 1, regardless of verdict. Usage resets on your billing period start.

Need something missing?

Email hello@bouncyboobs.dev.