Documentación

Los endpoints que realmente usas.

Una clave, dos endpoints: verificar una dirección o verificar una lista.

01Autenticación

Una clave, enviada como bearer token.

Cada petición lleva tu clave de API. Las claves se crean en el panel y llevan los scopes verify y bulk.

Authorization: Bearer bi_live_…
Content-Type: application/json

Una clave solo se muestra al crearla; guardamos únicamente el prefijo. Si se filtra, revócala y crea otra; el resto siguen funcionando.

02Individual / tiempo real

Verificar una dirección.

Comprobación síncrona: sintaxis, DNS, MX y una conversación SMTP con el servidor receptor. Un crédito.

POSThttps://api.bounceintel.com/v1/check_email

Verificar una dirección

Devuelve el informe puntuado completo. Latencia mediana por debajo de 500 ms; permite 30 s con servidores lentos.

verify.sh
curl -sS -X POST 'https://api.bounceintel.com/v1/check_email' \
  -H "Authorization: Bearer $BOUNCEINTEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]"
}'
Respuesta200
{
  "input": "[email protected]",
  "is_reachable": "safe",
  "provider": "google_workspace",
  "provider_confidence": "high",
  "score": {
    "score": 100,
    "category": "valid",
    "sub_reason": "deliverable",
    "safe_to_send": true,
    "confidence": 95,
    "confidence_level": "high",
    "reason_codes": ["provider_reputation"],
    "signals": {
      "valid_syntax": true,
      "has_mx_records": true,
      "smtp_can_connect": true,
      "smtp_is_deliverable": true,
      "smtp_is_catch_all": false
    }
  },
  "syntax": { "username": "ada", "domain": "stripe.com", "is_valid_syntax": true },
  "mx": { "accepts_mail": true, "records": ["aspmx.l.google.com."] },
  "smtp": {
    "can_connect_smtp": true,
    "is_deliverable": true,
    "is_catch_all": false,
    "has_full_inbox": false,
    "is_disabled": false
  },
  "misc": { "is_disposable": false, "is_role_account": false, "is_b2c": false },
  "bounce_risk": { "score": 8, "category": "low", "action": "send", "confidence": 0.71 }
}
mx, smtp y misc son uniones: o el objeto de detalle, o un objeto de error si la etapa no pudo completarse. Comprueba el tipo antes de leer.

03Masivo / asíncrono

Verificar una lista.

Envía la lista entera en una petición, consulta el progreso y pagina los resultados. Un crédito por dirección, cobrado al enviar.

POSThttps://api.bounceintel.com/v1/bulk

Enviar una lista

Envía todas las direcciones en una llamada. La respuesta es un id de trabajo; la verificación corre en segundo plano.

bulk.sh
curl -sS -X POST 'https://api.bounceintel.com/v1/bulk' \
  -H "Authorization: Bearer $BOUNCEINTEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ]
}'
Respuesta200
{
  "job_id": 8
}
Los créditos se cobran por el lote completo al enviarlo, de forma atómica: dos trabajos simultáneos no pueden gastar el mismo saldo. Si el lote supera tus créditos, se rechaza la petición entera; nada se cobra parcialmente.
GEThttps://api.bounceintel.com/v1/bulk/{job_id}

Consultar el progreso

Consulta mientras corre. finished_at sigue en null hasta procesar todas las direcciones.

status.sh
curl -sS -X GET 'https://api.bounceintel.com/v1/bulk/{job_id}' \
  -H "Authorization: Bearer $BOUNCEINTEL_KEY" \
  -H "Accept: application/json"
Respuesta200
{
  "job_id": 8,
  "created_at": "2026-09-02T15:16:15.447365Z",
  "finished_at": null,
  "total_records": 4,
  "total_processed": 2,
  "summary": {
    "total_safe": 1,
    "total_risky": 0,
    "total_invalid": 1,
    "total_unknown": 0
  },
  "job_status": "Running"
}
Consulta cada pocos segundos, no en bucle cerrado. Los totales del resumen se actualizan en vivo.
GEThttps://api.bounceintel.com/v1/bulk/{job_id}/results?format=json&limit=1000&offset=0

Obtener resultados

Pagina los resultados terminados. Cada fila tiene la misma forma que una verificación individual.

results.sh
curl -sS -X GET 'https://api.bounceintel.com/v1/bulk/{job_id}/results?format=json&limit=1000&offset=0' \
  -H "Authorization: Bearer $BOUNCEINTEL_KEY" \
  -H "Accept: application/json"
Respuesta200
{
  "results": [
    {
      "input": "[email protected]",
      "is_reachable": "safe",
      "provider": "google_workspace",
      "score": {
        "score": 100,
        "category": "valid",
        "safe_to_send": true,
        "sub_reason": "deliverable",
        "reason_codes": ["provider_reputation"]
      },
      "syntax": { "username": "ada", "domain": "stripe.com", "is_valid_syntax": true },
      "mx": { "accepts_mail": true, "records": ["aspmx.l.google.com."] },
      "smtp": { "can_connect_smtp": true, "is_deliverable": true, "is_catch_all": false },
      "misc": { "is_disposable": false, "is_role_account": false },
      "bounce_risk": { "score": 8, "category": "low", "action": "send" }
    }
  ]
}
limit es 50 por defecto en JSON. Indícalo explícitamente, hasta 1000, y pagina con offset. Usa format=csv para descargar todo como fichero.

04Asistentes de IA

Verifica desde tu asistente de IA.

BounceIntel ofrece un servidor MCP en https://api.bounceintel.com/mcp. Conecta Claude Code, Cursor, VS Code o cualquier cliente que hable MCP por HTTP, y el asistente verificará direcciones y listas por ti con la misma clave de API y los mismos créditos.

terminal
claude mcp add --transport http bounceintel https://api.bounceintel.com/mcp \
  --header "Authorization: Bearer $BOUNCEINTEL_KEY"

Envía tu clave de API como bearer token, igual que con la API REST. Los ejemplos la leen de BOUNCEINTEL_KEY, para que la clave no acabe en archivos que podrías subir al repositorio.

HerramientaScope de la claveQué hace
verify_emailverifyVerifica una dirección y devuelve el veredicto, la puntuación y el motivo. Un crédito.
verify_email_listbulkInicia un trabajo masivo para una lista y devuelve su id. Un crédito por dirección única.
get_bulk_jobbulkMuestra el progreso de un trabajo y cuántas direcciones hay de cada veredicto. No gasta créditos.
get_bulk_resultsbulkDevuelve los veredictos de un trabajo terminado, página a página y filtrados por veredicto si quieres. No gasta créditos.
get_accountcualquier claveMuestra el plan, los créditos restantes y cuándo se renuevan. No gasta créditos.

Los trabajos masivos se ejecutan en segundo plano: el asistente inicia el trabajo, consulta su progreso y después lee los resultados. Las herramientas que una clave no puede usar quedan ocultas para el asistente.

05Errores

Lo que puede devolver.

Cada fallo devuelve un JSON con un campo error. Estos son los que conviene tratar.

EstadoErrorQué hacer
400invalid_requestCuerpo mal formado o dirección inservible. Corrige y reenvía.
401unauthorizedClave ausente, incorrecta o revocada.
403forbiddenClave válida pero sin el scope necesario.
429rate_limitedDemasiadas peticiones. Espera y reintenta.
429quota_exceededSin créditos. Solo comprar más lo resuelve; reintentar no ayuda.
503unavailableNo pudimos establecer tu cuota. Transitorio: reintenta en breve.

06Zona de pruebas

Pruébalo con tu clave.

Ejecuta una verificación real en tu cuenta. Una dirección gasta un crédito; el bulk gasta uno por dirección al enviar el trabajo.

Pega tu propia clave de API para probarlo. La clave se envía a nuestro backend, se usa una vez y no se almacena. Las comprobaciones de invitado no usan tu clave.

URL base: https://api.bounceintel.com

POST https://api.bounceintel.com/v1/check_email

verify.sh
curl -sS -X POST 'https://api.bounceintel.com/v1/check_email' \
  -H "Authorization: Bearer $BOUNCEINTEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]"
}'

Los fragmentos copiados usan $BOUNCEINTEL_KEY, nunca la clave que escribiste.