POST /v1/verify/batch

Verifica fino a 500.000 email in modo asincrono. Usalo per pulire liste esistenti, non per i flussi di registrazione in tempo reale.

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

Invia una lista di indirizzi. Restituisce subito un job_id; interroga GET /v1/jobs/:id per vedere l'avanzamento.

Corpo della richiesta

Parameters

Name	Type	Required	Description
`emails`	string[]	required	Array di indirizzi email. Massimo 500.000 per lotto.

Risposta all'invio

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"
}

L'invio è una richiesta contro il tuo limite di ritmo, non una per indirizzo. Ogni indirizzo del lotto conta come una verifica contro la tua quota mensile. Se il tuo piano non ammette eccedenze e il lotto è più grande di quello che ti resta, l'intero invio viene rifiutato con un 429 quota_exceeded invece di fermarsi a metà della tua lista.

GET /v1/jobs/:id

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

Interroga un lavoro in blocco. status è queued, processing, completed oppure failed.

Risposta — completato200 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 si aggiorna mentre il lavoro gira, così puoi mostrare un avanzamento reale. download_url compare quando il lavoro finisce e finché i risultati restano dentro la finestra di conservazione.

GET /v1/jobs/:id/results

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

Scarica i risultati. CSV per impostazione predefinita; aggiungi ?format=json per le stesse righe in JSON.

Il CSV porta una riga di intestazione — email,status,score,reason — e una riga per indirizzo, nell'ordine in cui li hai inviati. La forma JSON aggiunge index così puoi incrociare i risultati con la tua lista.

Risposta — ?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"
}

Errori

404 not_found — quel lavoro non esiste, oppure appartiene a un altro account. Le due cose sono indistinguibili di proposito.
409 job_not_ready — il lavoro non è ancora finito.
410 results_expired — sono passate le 72 ore e i risultati sono stati cancellati.

Preferisci non scrivere codice? Il pannello accetta un CSV e ti restituisce la lista pulita.