PARA DESARROLLADORES

API de verificación de email.

Verifica una dirección para formularios o utiliza tareas asíncronas para listas de clientes. Conserva tu proveedor de email.

EMPIEZA CON UNA DIRECCIÓN

Tu primera solicitud.

Utiliza el endpoint de prueba gratuito sin clave. Tiene límites de solicitudes y sirve para probar el servicio.

curl -X POST https://api.zbounce.net/v1/demo \
  -H 'Content-Type: application/json' \
  -d '{"email":"hello@example.com"}'

Para verificaciones de pago, compra un paquete y utiliza /v1/fast-verify con tu clave en X-API-Key. No incluyas claves en URLs, repositorios ni analíticas.

curl -X POST https://api.zbounce.net/v1/fast-verify \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $ZBOUNCE_API_KEY" \
  -d '{"email":"hello@example.com"}'

Ejemplo en Python

import os, requests

response = requests.post(
    "https://api.zbounce.net/v1/fast-verify",
    headers={"X-API-Key": os.environ["ZBOUNCE_API_KEY"]},
    json={"email": "hello@example.com"},
    timeout=35,
)
response.raise_for_status()
print(response.json())

Ejemplo en Node.js

const response = await fetch("https://api.zbounce.net/v1/fast-verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.ZBOUNCE_API_KEY,
  },
  body: JSON.stringify({ email: "hello@example.com" }),
  signal: AbortSignal.timeout(35000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

ENTRA UNA LISTA, SALEN RESULTADOS

Verifica una lista más grande.

POST /v1/tasks

Envía hasta 10.000 direcciones por tarea. Guarda el ID devuelto y revisa accepted, skipped y invalids: no todas las entradas se añaden necesariamente a la cola. Pueden excluirse direcciones duplicadas, mal formadas o suprimidas, y un saldo bajo puede causar una aceptación parcial.

curl -X POST https://api.zbounce.net/v1/tasks \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $ZBOUNCE_API_KEY" \
  -d '{"emails":["hello@example.com","contact@example.org"]}'

Consulta el estado y recupera cada página de resultados. Una respuesta con solo entradas inválidas puede tener un ID vacío; no consultes su estado.

curl "https://api.zbounce.net/v1/tasks/$TASK_ID" \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

curl "https://api.zbounce.net/v1/tasks-results/$TASK_ID?page=1&per_page=100" \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

Los resultados de las tareas completadas están en JSON. Sigue recuperando páginas hasta obtener toda la lista aceptada. Para notificar la finalización automáticamente, envía un webhook con mode: "completed" al crear la tarea.

{
  "emails": ["hello@example.com"],
  "webhook": {
    "url": "https://your-app.example/hooks/verification",
    "mode": "completed",
    "secret": "YOUR_PRIVATE_WEBHOOK_SECRET"
  }
}

Consulta el esquema de configuración del webhook y verificación de firma antes de habilitarlo en producción.

ENTIENDE LA RESPUESTA

El formato no implica existencia.

Son señales diferentes. Una dirección bien formada puede no existir, ser temporal o no poder confirmarse.

Campo	Significado
`valid`	La dirección superó la validación de sintaxis. Esto no confirma por sí solo el buzón.
`exists`	Resultado de la comprobación del buzón. Interprétalo junto con errores y señales catch-all.
`disposable`	El dominio se reconoció como proveedor de email temporal.
`accept_all`	El servidor acepta direcciones arbitrarias; no se puede confirmar el buzón concreto de forma fiable.
`error_category`	Explica un fallo o riesgo, como no_mx, risky o un problema temporal del servidor.
`permanent_error`	Se recibió un fallo permanente durante la verificación. Un fallo temporal no debe interpretarse como un rechazo permanente.
`ttl`	Indicación del tiempo de reintento o caché en segundos, cuando se devuelve.

La verificación no garantiza la entrega, no elimina las quejas ni demuestra la propiedad de un buzón.

Conoce tu saldo.

GET /v1/me

curl https://api.zbounce.net/v1/me \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

La respuesta incluye créditos disponibles, reservados y utilizados, tipo de clave y vencimiento. Una verificación estándar usa un crédito; el filtrado y cobro dependen de la ruta y la aceptación de la tarea. Revisa la respuesta antes de considerar procesada toda la lista subida.

Una respuesta 429 indica límites de solicitudes. Espera antes de reintentar. Otros errores de la API actual pueden devolverse en JSON o texto; no los interpretes como resultados de verificación.

El contrato de verificación.

Descargar OpenAPI JSON

El contrato público incluye demo, verificación rápida, tareas, estado, resultados y saldo. Los endpoints de envío y administración quedan fuera de esta referencia.

¿Necesitas ayuda para conectar tu plataforma? support@zbounce.net