POST /v1/verify/batch

Vérifie jusqu'à 500 000 adresses de façon asynchrone. À utiliser pour nettoyer des listes existantes, pas pour un parcours d'inscription en temps réel.

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

Envoie une liste d'adresses. Renvoie immédiatement un job_id ; interrogez GET /v1/jobs/:id pour suivre l'avancement.

Corps de la requête

Parameters

Name	Type	Required	Description
`emails`	string[]	required	Tableau d'adresses e-mail. 500 000 au maximum par lot.

Réponse à l'envoi

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'envoi compte pour une requête contre votre limite de débit, pas une par adresse. En revanche, chaque adresse du lot compte comme une vérification contre votre quota mensuel. Si votre forfait n'admet pas de dépassement et que le lot est plus grand que ce qu'il vous reste, l'envoi entier est rejeté par un 429 quota_exceeded plutôt que de s'arrêter au milieu de votre liste.

GET /v1/jobs/:id

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

Interroge une tâche par lots. status vaut queued, processing, completed ou failed.

Réponse — terminée200 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 met à jour pendant l'exécution de la tâche, ce qui vous permet d'afficher un avancement réel. download_url apparaît une fois la tâche terminée, et tant que les résultats restent dans la fenêtre de conservation.

GET /v1/jobs/:id/results

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

Télécharge les résultats. CSV par défaut ; ajoutez ?format=json pour les mêmes lignes en JSON.

Le CSV porte une ligne d'en-tête — email,status,score,reason — et une ligne par adresse, dans l'ordre où vous les avez envoyées. La forme JSON ajoute index pour que vous puissiez rapprocher les résultats de votre propre liste.

Réponse — ?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"
}

Erreurs

404 not_found — cette tâche n'existe pas, ou elle appartient à un autre compte. Les deux cas sont indiscernables à dessein.
409 job_not_ready — la tâche n'est pas encore terminée.
410 results_expired — les 72 heures sont passées et les résultats ont été supprimés.

Vous préférez ne pas écrire de code ? Le tableau de bord accepte un CSV et vous rend la liste nettoyée.