Batches

Les batches vérifient une liste d'adresses en une seule soumission plutôt qu'un appel POST /api/verify par adresse. Les endpoints de batch acceptent comme bearer soit votre jeton d'accès JWT du dashboard, soit une clé API pm_, de sorte qu'une intégration côté serveur peut nettoyer une liste avec la même clé qu'elle utilise pour la vérification unitaire. Une clé doit porter le scope email:verify:bulk pour les endpoints de soumission et results:read pour les lectures.

Soumettre un batch

POST /api/batches prend une liste d'emails, la normalise et la déduplique côté serveur, puis met en file un job par adresse valide unique. Une adresse syntaxiquement invalide ou en double ne devient jamais un job ; elle est comptée dans syntax_errors ou duplicates sur la réponse à la place.

curl -X POST https://api.pricklymails.com/api/batches \
  -H "Authorization: Bearer votre_jeton_jwt" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Liste newsletter", "emails": ["a@example.com", "b@example.com"] }'

La réponse est 202 Accepted avec un en-tête Location pointant vers l'URL d'interrogation et un Retry-After :

{
    "batch_uuid": "6f1c...",
    "status": "processing",
    "total_jobs": 2,
    "syntax_errors": 0,
    "duplicates": 0,
    "estimated_cost": 14
}

Votre plan détermine quels checks peuvent être demandés ; omettez-le et le batch prend par défaut tous les contrôles autorisés par votre plan, SMTP inclus. Désélectionnez un contrôle pour réduire le batch et son coût ; un contrôle non autorisé renvoie 403. Le coût total est réservé sur votre portefeuille de façon atomique, en même temps que le batch et ses jobs, donc un manque de solde (402) ou un contrôle non autorisé (403) ne laisse jamais de jobs partiels derrière lui. Une seule requête accepte jusqu'à 4 096 emails ; 400 est renvoyé pour une liste trop grande, ou quand toutes les adresses ont été rejetées.

Streamer une liste plus grande

Passez final: false à la soumission ci-dessus pour garder l'intake du batch ouvert, puis ajoutez d'autres tranches :

curl -X POST https://api.pricklymails.com/api/batches/6f1c.../emails \
  -H "Authorization: Bearer votre_jeton_jwt" \
  -H "Content-Type: application/json" \
  -d '{ "emails": ["c@example.com"], "final": true }'

Chaque tranche (jusqu'à 4 096 emails, le même plafond par requête) réserve et met en file ses jobs comme la première, augmentant le progress.total du batch, jusqu'au plafond de 1 000 000 d'emails du domaine. La déduplication entre tranches n'est pas effectuée : une tranche ne se déduplique que contre elle-même. Passez final: true sur la dernière tranche pour fermer l'intake ; le batch se termine alors dès que tous les jobs (anciens et nouveaux) ont fini. Renvoie 409 si l'intake est déjà fermé ou si le batch est terminal, et 404 pour un batch que vous ne possédez pas.

Lister et interroger

GET /api/batches liste vos batches, les plus récents en premier, paginé (limit par défaut 20, plafond 96 ; offset).

GET /api/batches/{uuid} renvoie le statut, la progression et les résultats agrégés d'un batch :

{
    "uuid": "6f1c...",
    "status": "processing",
    "progress": { "total": 2, "processed": 1, "succeeded": 1, "failed": 0, "skipped": 0, "percent_complete": 50 },
    "results": { "valid": 1, "invalid": 0, "risky": 0, "unknown": 0, "duplicates": 0, "syntax_errors": 0 },
    "created_at": "2026-08-01T12:00:00Z",
    "updated_at": "2026-08-01T12:00:04Z"
}

GET /api/batches/{uuid}/results renvoie les résultats par email, dans l'ordre de soumission, paginé de la même façon. Un uuid de batch appartenant à autrui renvoie le même 404 qu'un uuid inconnu. Chaque ligne :

{
    "uuid": "6f1c...",
    "status": "completed",
    "score": 76,
    "verdict": "risky",
    "recommendation": "send",
    "custom_id": "crm-42"
}

verdict et score se remplissent une fois le job terminal. recommendation est l'action à prendre pour le nettoyage de liste, dérivée du verdict : remove (invalide, jetable, faute de frappe, domaine mort), send (valide, ou un fournisseur accept-all grand public auquel vous envoyez normalement même s'il ne peut être confirmé), ou review (catch-all, rôle, boîte pleine, ou une sonde non concluante). custom_id renvoie ce que vous avez fourni pour cette adresse à la soumission (null si rien), pour mapper un résultat à votre propre ligne sans vous fier à l'ordre.