POST /v1/verify/batch

Verifica hasta 500 000 emails de forma asíncrona. Úsalo para limpiar listas existentes, no para flujos de registro en tiempo real.

POSThttps://api.mailbeam.dev/v1/verify/batch

Envía una lista de direcciones. Devuelve un job_id de inmediato; consulta GET /v1/jobs/:id para ver el progreso.

Cuerpo de la petición

Parameters

Name	Type	Required	Description
`emails`	string[]	required	Array de direcciones de email. Máximo 500 000 por lote.

Respuesta al envío

Response202 Accepted

{
  "job_id": "job_9f2c1d7a-4b83-4a1e-9f0e-2b6c5d8a1f34",
  "status": "queued",
  "total": 5000,
  "created_at": "2026-08-10T14:32:00Z",
  "results_expire_at": "2026-08-13T14:32:00Z",
  "request_id": "req_7d4a1c9e"
}

El envío es una petición contra tu límite de tasa, no una por dirección. Cada dirección del lote cuenta como una verificación contra tu cuota mensual. Si tu plan no admite exceso y el lote es mayor que lo que te queda, se rechaza el envío entero con un 429 quota_exceeded en vez de parar a mitad de tu lista.

GET /v1/jobs/:id

GEThttps://api.mailbeam.dev/v1/jobs/:id

Consulta un trabajo por lotes. status es queued, processing, completed o failed.

Respuesta — completado200 OK

{
  "job_id": "job_9f2c1d7a-4b83-4a1e-9f0e-2b6c5d8a1f34",
  "status": "completed",
  "total": 5000,
  "processed": 5000,
  "valid": 4213,
  "invalid": 787,
  "created_at": "2026-08-10T14:32:00Z",
  "completed_at": "2026-08-10T14:36:48Z",
  "results_expire_at": "2026-08-13T14:32:00Z",
  "download_url": "https://api.mailbeam.dev/v1/jobs/job_9f2c1d7a-4b83-4a1e-9f0e-2b6c5d8a1f34/results",
  "request_id": "req_7d4a1c9f"
}

processed se actualiza mientras el trabajo corre, así que puedes mostrar progreso real. download_url aparece cuando el trabajo termina y mientras los resultados sigan dentro de la ventana de conservación.

GET /v1/jobs/:id/results

GEThttps://api.mailbeam.dev/v1/jobs/:id/results

Descarga los resultados. CSV por defecto; añade ?format=json para las mismas filas en JSON.

El CSV lleva una fila de cabecera — email,status,score,reason — y una fila por dirección, en el orden en que las enviaste. La forma JSON añade index para que puedas cruzar los resultados con tu propia lista.

Respuesta — ?format=json200 OK

{
  "job_id": "job_9f2c1d7a-4b83-4a1e-9f0e-2b6c5d8a1f34",
  "results": [
    {
      "index": 0,
      "email": "jane@example.com",
      "status": "deliverable",
      "score": 94,
      "reason": null
    },
    {
      "index": 1,
      "email": "old@example.com",
      "status": "undeliverable",
      "score": 5,
      "reason": "smtp_rejected"
    },
    {
      "index": 2,
      "email": "info@example.com",
      "status": "risky",
      "score": 55,
      "reason": "catch_all"
    }
  ],
  "request_id": "req_7d4a1ca0"
}

Errores

404 not_found — no existe ese trabajo, o pertenece a otra cuenta. Las dos cosas son indistinguibles a propósito.
409 job_not_ready — el trabajo todavía no ha terminado.
410 results_expired — han pasado las 72 horas y los resultados se han borrado.

¿Prefieres no escribir código? El panel acepta un CSV y te devuelve la lista limpia.