Documentación de la API

Después de registrarte, tenés una API key bb_live_... con 500 créditos gratis. Con eso ya podés hacer verificaciones. Base URL:

https://api.byebouncer.com

curl -X POST https://api.byebouncer.com/api/v1/verify \
  -H "Authorization: Bearer bb_live_xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "someone@example.com"}'

Todos los endpoints que consumen créditos requieren el header Authorization: Bearer <api_key>.

• Live keys (bb_live_*): backend, sin restricción de dominio, todos los endpoints.
• Public keys (bb_pub_*): frontend (widget JS), CORS restringido por dominio y acceso autenticado solo a /verify. /suggest es público y no necesita key.

Nunca commitees API keys al repo. Rotalas desde el dashboard si sospechás compromiso.

Verifica un email. Corta la respuesta cache-hit (misma dirección en última hora) sin consumir crédito.

Request

{
  "email": "someone@example.com"
}

Response (200)

{
  "email": "someone@example.com",
  "status": "deliverable",
  "action": "allow",
  "flagged": false,
  "signals": [
    "valid_syntax",
    "mx_found",
    "mailbox_accepts_mail"
  ],
  "domain": {
    "name": "example.com",
    "type": "business",
    "disposable": false,
    "free_provider": false,
    "has_mx": true
  },
  "cached": false,
  "response_time_ms": 1230,
  "credits_remaining": 499,
  "verified_at": "2026-08-18T15:30:00Z"
}

curl -X POST https://api.byebouncer.com/api/v1/verify \
  -H "Authorization: Bearer bb_live_xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "someone@example.com"}'

Detecta typos en el dominio y devuelve una sugerencia si la distancia Levenshtein contra un dominio conocido es ≤ 2. No hace lookup de red.

curl -X POST https://api.byebouncer.com/api/v1/suggest \
  -H "Content-Type: application/json" \
  -d '{"email": "user@gnail.com"}'
# → { "suggestion": "user@gmail.com", ... }

Clasifica un dominio (disposable/free/business/education) + MX lookup. Útil para páginas de SEO o quick-check antes de registrar.

curl https://api.byebouncer.com/api/v1/domain/mailinator.com
# → { "domain": "mailinator.com", "type": "disposable", ... }

Balance actual de la key usada. Se lee siempre desde DB (nunca del cache).

curl https://api.byebouncer.com/api/v1/credits \
  -H "Authorization: Bearer bb_live_xxxxxxxxxx"

Estado del servicio. Devuelve ok o degraded según ping a Postgres + Redis. Podés apuntar Better Uptime u otro monitor externo.

Aplicamos rate limiting con sliding window en Redis. Headers en toda respuesta:

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1723644800