Traitement batch CSV

Validez des milliers d'emails en une seule opération asynchrone.

Cas d'usage

Nettoyer une liste de contacts existante
Qualifier des leads importés depuis un CRM/ERP
Vérifier une liste d'abonnés newsletter
Préparer une campagne emailing pour maximiser la délivrabilité

Formats supportés

Format	Extension	Notes
CSV	`.csv`	Séparateur auto-détecté (`,`, `;`, `\t`)
Texte	`.txt`	Un email par ligne
Excel	`.xlsx`	Première colonne email détectée

Taille max : 10 Mo — ~200 000 emails par fichier

Workflow complet

Parse (optionnel)     → Aperçu du fichier, détection de la colonne email
Upload                → Création du job asynchrone
Polling du statut     → Suivi de la progression en temps réel
Export                → CSV / XLSX / PDF

Étape 1 — Parser le fichier (optionnel)

curl -X POST https://api.yeswecheck.fr/v2/batch/parse \
  -H "Authorization: Bearer VOTRE_JWT" \
  -F "file=@liste_clients.csv"

{
  "headers": ["id", "prenom", "nom", "email", "ville"],
  "detectedEmailColumn": "email",
  "rowCount": 15420,
  "separator": ",",
  "preview": [
    { "id": "1", "prenom": "Jean", "nom": "Dupont", "email": "[email protected]" },
    { "id": "2", "prenom": "Marie", "nom": "Martin", "email": "[email protected]" }
  ]
}

Étape 2 — Lancer le traitement

cURL
JavaScript
Python

# Sans SMTP (gratuit, rapide)
curl -X POST https://api.yeswecheck.fr/v2/batch/upload \
  -H "Authorization: Bearer VOTRE_JWT" \
  -F "file=@liste_clients.csv" \
  -F "smtp=false" \
  -F "deduplicate=true" \
  -F "label=Liste Q1 2026"

# Avec SMTP complet (multi-pass)
curl -X POST https://api.yeswecheck.fr/v2/batch/upload \
  -H "Authorization: Bearer VOTRE_JWT" \
  -F "file=@liste_clients.csv" \
  -F "smtp=true" \
  -F "smtpTimeout=8000" \
  -F "pass2Enabled=true" \
  -F "deduplicate=true" \
  -F "label=Campagne emailing mars"

const formData = new FormData();
formData.append('file', csvFile);
formData.append('smtp', 'false');
formData.append('deduplicate', 'true');
formData.append('label', 'Liste Q1 2026');

const response = await fetch('https://api.yeswecheck.fr/v2/batch/upload', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${jwt}` },
  body: formData,
});

const { jobId } = await response.json();
console.log('Job créé:', jobId);

import httpx

async def upload_batch(file_path: str, jwt: str) -> str:
    async with httpx.AsyncClient() as client:
        with open(file_path, 'rb') as f:
            response = await client.post(
                "https://api.yeswecheck.fr/v2/batch/upload",
                headers={"Authorization": f"Bearer {jwt}"},
                files={"file": f},
                data={
                    "smtp": "false",
                    "deduplicate": "true",
                    "label": "Ma liste",
                },
                timeout=60.0,
            )
        response.raise_for_status()
        return response.json()["jobId"]

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "totalEmails": 15420,
  "fileName": "liste_clients.csv",
  "label": "Liste Q1 2026",
  "createdAt": "2026-02-25T10:00:00.000Z"
}

Étape 3 — Suivre la progression

Interrogez le statut toutes les 2-5 secondes :

curl https://api.yeswecheck.fr/v2/batch/550e8400-e29b-41d4-a716-446655440000/status \
  -H "Authorization: Bearer VOTRE_JWT"

Phases de traitement (avec SMTP)

┌────────────────────────────────────────────────────────┐
│                  Progression SMTP Batch                │
├──────────┬───────────────┬───────────┬─────────────────┤
│  Phase   │    Poids %    │  Vitesse  │   Description   │
├──────────┼───────────────┼───────────┼─────────────────┤
│ Pass 0   │     10%       │  Rapide   │ Syntaxe + DNS   │
│ Pass 1   │     70%       │  Lent     │ SMTP (1ère pass)│
│ Pass 2 * │     20%       │  Lent     │ Retry Unknown   │
└──────────┴───────────────┴───────────┴─────────────────┘
* Si pass2Enabled: true

Réponse de statut

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "progress": {
    "processed": 7210,
    "total": 15420,
    "valid": 5834,
    "invalid": 1089,
    "risky": 287,
    "unknown": 0,
    "percentage": 47
  },
  "currentPhase": "smtp_verification",
  "estimatedTimeRemaining": "8m30s",
  "smtp": {
    "enabled": true,
    "downgraded": false
  },
  "multiPass": {
    "pass0Done": true,
    "pass1Done": false,
    "smtpEligibleCount": 12400,
    "pass1Count": 5210
  }
}

Polling avec JavaScript

async function waitForCompletion(jobId, jwt) {
  while (true) {
    const status = await fetch(
      `https://api.yeswecheck.fr/v2/batch/${jobId}/status`,
      { headers: { 'Authorization': `Bearer ${jwt}` } }
    ).then(r => r.json());

    console.log(`${status.progress.percentage}% — ${status.currentPhase}`);
    console.log(`✅ ${status.progress.valid} | ❌ ${status.progress.invalid} | ⚠️ ${status.progress.risky}`);
    console.log(`⏱️ Reste: ${status.estimatedTimeRemaining}`);

    if (status.status === 'completed' || status.status === 'failed') {
      return status;
    }

    // Attendre 3 secondes avant le prochain check
    await new Promise(resolve => setTimeout(resolve, 3000));
  }
}

const finalStatus = await waitForCompletion(jobId, jwt);
console.log('Terminé !', finalStatus.progress);

Étape 4 — Exporter les résultats

Préparer l'export (recommandé pour les grandes listes)

L'export est généré en arrière-plan et envoyé par email (lien valide 48h) :

curl -X POST https://api.yeswecheck.fr/v2/batch/JOB_ID/export/prepare \
  -H "Authorization: Bearer VOTRE_JWT" \
  -H "Content-Type: application/json" \
  -d '{"format": "csv"}'

{
  "exportId": "exp_abc123",
  "message": "Un lien de téléchargement (valide 48h) sera envoyé par email dès que l'export est prêt."
}

Vérifier si l'export est prêt

curl "https://api.yeswecheck.fr/v2/batch/JOB_ID/export/status?format=csv" \
  -H "Authorization: Bearer VOTRE_JWT"

{
  "status": "ready",
  "downloadUrl": "https://exports.yeswecheck.fr/abc123.csv?token=...",
  "expiresAt": "2026-02-27T10:00:00.000Z"
}

Télécharger le rapport PDF

curl https://api.yeswecheck.fr/v2/batch/JOB_ID/download-pdf \
  -H "Authorization: Bearer VOTRE_JWT" \
  --output rapport-batch.pdf

Gestion des jobs

# Lister tous les jobs (avec filtres)
curl "https://api.yeswecheck.fr/v2/batch/jobs?status=completed&limit=20" \
  -H "Authorization: Bearer VOTRE_JWT"

# Mettre en pause
curl -X POST https://api.yeswecheck.fr/v2/batch/JOB_ID/pause \
  -H "Authorization: Bearer VOTRE_JWT"

# Reprendre
curl -X POST https://api.yeswecheck.fr/v2/batch/JOB_ID/resume \
  -H "Authorization: Bearer VOTRE_JWT"

# Annuler
curl -X POST https://api.yeswecheck.fr/v2/batch/JOB_ID/cancel \
  -H "Authorization: Bearer VOTRE_JWT"

# Supprimer (job terminé uniquement)
curl -X DELETE https://api.yeswecheck.fr/v2/batch/JOB_ID \
  -H "Authorization: Bearer VOTRE_JWT"

Structure du CSV exporté

Colonne	Description
`email`	Adresse email originale
`status`	`valid`, `invalid`, `risky`, `unknown`
`score`	Score de 0 à 100
`syntax_valid`	true/false
`has_mx_records`	true/false
`is_disposable`	true/false
`is_role_account`	true/false
`smtp_deliverable`	true/false/null
`smtp_response_code`	250, 550, etc.
`typo_suggestion`	Email corrigé suggéré

Bonnes pratiques batch

Performance SMTP

Pour les grandes listes avec SMTP, le traitement est groupé par serveur MX. Les serveurs stricts (Google, Microsoft) peuvent répondre lentement — prévoyez 1-4h pour 10 000 emails SMTP.

pass2Enabled

Le Pass 2 re-vérifie les emails unknown (timeout SMTP au Pass 1) avec un délai. Recommandé pour les campagnes critiques. Ajoute ~20% de temps de traitement.

Cas d'usage​

Formats supportés​

Workflow complet​

Étape 1 — Parser le fichier (optionnel)​

Étape 2 — Lancer le traitement​

Étape 3 — Suivre la progression​

Phases de traitement (avec SMTP)​

Réponse de statut​

Polling avec JavaScript​

Étape 4 — Exporter les résultats​

Préparer l'export (recommandé pour les grandes listes)​

Vérifier si l'export est prêt​

Télécharger le rapport PDF​

Gestion des jobs​

Structure du CSV exporté​

Bonnes pratiques batch​