Desarrolladores

Una API de verificación de correo que simplemente funciona

Verifica una dirección en tiempo real o envía una lista completa como lote. Todas las solicitudes usan HTTPS y devuelven JSON. Crea claves de API en tu panel, en Claves de API.

Obtén una clave de API Leer la referencia

REST y JSON
Callbacks de lotes
Los mismos créditos que en el panel

La página de claves de API de BounceBell con claves activas y un formulario para crear una clave nueva

verify.sh

# Verify one addresscurl "https://bouncebell.com/api/v1/verify?email=rini.elizabeth@acme-foods.com" \  -H "Authorization: Bearer YOUR_API_KEY" { "status": "valid",  "reason": "mailbox_exists",  "did_you_mean": null }

Autenticación

Envía tu clave de API como token bearer en la cabecera Authorization en cada solicitud. Guarda las claves en tu servidor. Nunca las pongas en código del navegador ni en apps móviles.

Authorization: Bearer YOUR_API_KEY

La URL base de todos los endpoints es https://bouncebell.com/api/v1.

Verificar una dirección

GET https://bouncebell.com/api/v1/verify

Parámetro	Obligatorio	Descripción
`email`	Sí	La dirección a verificar. Codifícala para URL.
`timeout`	No	Segundos de espera al servidor de correo, de 3 a 30. Por defecto, 10. Si se agota el tiempo, el estado es `unknown` y no se usa ningún crédito.

Ejemplo

curl "https://bouncebell.com/api/v1/verify?email=rini.elizabeth%40acme-foods.example" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "email": "rini.elizabeth@acme-foods.example",
  "status": "valid",
  "reason": "mailbox_exists",
  "domain": "acme-foods.example",
  "mx_record": "mx1.acme-foods.example",
  "disposable": false,
  "role": false,
  "free_provider": false,
  "catch_all": false,
  "did_you_mean": null,
  "checked_at": "2026-10-30T09:30:12Z",
  "credits_used": 1
}

Campos del resultado

Campo	Tipo	Descripción
`email`	string	La dirección tal como la enviaste.
`status`	string	El veredicto. Consulta los estados.
`reason`	string	Por qué llegamos al veredicto, por ejemplo `mailbox_not_found` o `no_mail_server`.
`domain`	string	La parte del dominio, en minúsculas.
`mx_record`	string or null	El servidor de correo con la prioridad más alta.
`disposable`	boolean	True si el dominio es un servicio de buzones temporales.
`role`	boolean	True para buzones compartidos como info@ o support@.
`free_provider`	boolean	True para proveedores de correo gratuitos como Gmail.
`catch_all`	boolean	True cuando el dominio acepta cualquier dirección.
`did_you_mean`	string or null	Una dirección corregida cuando el dominio parece una errata.
`checked_at`	string	Cuándo se realizó la verificación, en ISO 8601 UTC.
`credits_used`	integer	1, o 0 cuando el estado es `unknown`.

Estados

Estado	Significado	Acción sugerida
`valid`	El buzón existe y acepta correo.	Enviar
`invalid`	La dirección, el dominio o el buzón no existe.	Eliminar
`disposable`	Un servicio de buzones temporales.	Eliminar
`catch_all`	El dominio acepta todas las direcciones, así que no se puede confirmar el buzón.	Revisar
`role`	Un buzón compartido que existe.	Revisar
`unknown`	El servidor de correo no respondió a tiempo. Sin cargo.	Reintentar más tarde

Lotes

Envía hasta 100.000 direcciones en una sola solicitud. El lote se procesa en segundo plano; consulta su estado o indica una callback_url y la llamaremos cuando el lote termine.

Crear un lote

POST https://bouncebell.com/api/v1/batches

curl -X POST "https://bouncebell.com/api/v1/batches" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "October import", "emails": ["a@example.com", "b@example.com"],
       "callback_url": "https://yourapp.example/hooks/bouncebell"}'

{ "id": "bat_8f2k1q3m9x7w4p", "status": "queued", "total": 2, "done": 0 }

Los créditos de cada dirección única se reservan al crear el lote, y los resultados desconocidos se reembolsan al terminar. El callback recibe un POST con {"event": "batch.completed", "batch_id": "...", "status": "done", "counts": {...}}. Las URL de callback deben usar HTTPS.

Consultar el progreso

GET https://bouncebell.com/api/v1/batches/{id}

{ "id": "bat_8f2k1q3m9x7w4p", "status": "running", "total": 2, "done": 1 }

El estado es queued, running o done. Cuando es done, la respuesta también incluye counts por estado.

Descargar resultados

GET https://bouncebell.com/api/v1/batches/{id}/results

Devuelve JSON de forma predeterminada. Añade ?format=csv para obtener un archivo CSV. Cada fila tiene los mismos campos que una verificación individual.

Créditos

GET https://bouncebell.com/api/v1/credits

{ "credits_remaining": 33420 }

Errores y límites

Los errores devuelven un cuerpo JSON con un código error y un message legible.

Código HTTP	Error	Qué hacer
400	`bad_request`	Falta un parámetro o es incorrecto. Lee el mensaje.
401	`invalid_key`	Comprueba que la clave sea correcta y no se haya revocado.
402	`no_credits`	Compra más créditos.
403	`email_not_confirmed`	Abre el enlace de confirmación que te enviamos por correo al registrarte.
404	`not_found`	El lote no existe o se eliminó después de 30 días.
429	`rate_limited`	Reduce el ritmo. Espera los segundos indicados en la cabecera `Retry-After`.
500	`server_error`	Reintenta tras una breve espera. Si continúa, contacta con soporte.

Las verificaciones individuales están limitadas a 20 solicitudes por segundo por clave. Pídenos más si lo necesitas.