Validation par lot

Authentification

Incluez votre clé API dans l'en-tête X-API-Key :

X-API-Key: ml_pv_Ab3Kx9mN2pQ7rT4wL8yD...

L'identifiant doit être un identifiant produit Validation avec le canal Api activé.

Valider un lot

POST https://api.mail.land/v1/validation/batch

Requête de validation par lot

{
  "emails": [
    "[email protected]",
    "[email protected]",
    "invalid@",
    "[email protected]",
    "[email protected]"
  ],
  "verify_smtp": true
}

Champ	Type	Défaut	Description
`emails`	array	-	Adresses email à valider (obligatoire, max 100)
`verify_smtp`	bool	true	Effectuer la vérification SMTP de la boîte aux lettres

Batch validate

curl -X POST https://api.mail.land/v1/validation/batch \
  -H "X-API-Key: ml_pv_Ab3Kx9mN2pQ7rT4wL8yD..." \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["[email protected]", "[email protected]", "[email protected]"],
    "verify_smtp": true
  }'

Réponse

Réponse de validation par lot

{
  "total_count": 5,
  "processed_count": 5,
  "successful_count": 5,
  "credits_consumed": 4,
  "free_validations": 1,
  "results": [
    {
      "email": "[email protected]",
      "result": "Deliverable",
      "score": 95,
      "syntax": { "is_valid": true, "has_typo": false },
      "disposable": { "is_disposable": false },
      "role": { "is_role_account": false },
      "mx": { "has_mx": true, "records": ["mx.example.com"], "accepts_mail": true },
      "smtp": { "can_connect": true, "is_deliverable": true, "is_catch_all": false, "reachability": "safe" },
      "provider": { "name": "Unknown", "type": "unknown" },
      "cached": false,
      "verified_at": "2026-02-17T12:34:56Z"
    },
    {
      "email": "[email protected]",
      "result": "Deliverable",
      "score": 95,
      "syntax": { "is_valid": true, "has_typo": false },
      "disposable": { "is_disposable": false },
      "role": { "is_role_account": false },
      "mx": { "has_mx": true, "records": ["gmail-smtp-in.l.google.com"], "accepts_mail": true },
      "smtp": { "can_connect": true, "is_deliverable": true, "is_catch_all": false, "reachability": "safe" },
      "provider": { "name": "Gmail", "type": "consumer" },
      "cached": false,
      "verified_at": "2026-02-17T12:34:56Z"
    },
    {
      "email": "invalid@",
      "result": "Undeliverable",
      "score": 0,
      "syntax": { "is_valid": false, "has_typo": false },
      "disposable": { "is_disposable": false },
      "role": { "is_role_account": false },
      "mx": { "has_mx": false, "records": [], "accepts_mail": false },
      "smtp": null,
      "provider": { "name": "Unknown", "type": "unknown" },
      "cached": false,
      "verified_at": "2026-02-17T12:34:56Z"
    },
    {
      "email": "[email protected]",
      "result": "Undeliverable",
      "score": 10,
      "syntax": { "is_valid": true, "has_typo": false },
      "disposable": { "is_disposable": true },
      "role": { "is_role_account": false },
      "mx": { "has_mx": true, "records": ["mx.tempmail.org"], "accepts_mail": true },
      "smtp": null,
      "provider": { "name": "Unknown", "type": "unknown" },
      "cached": false,
      "verified_at": "2026-02-17T12:34:56Z"
    },
    {
      "email": "[email protected]",
      "result": "Deliverable",
      "score": 85,
      "syntax": { "is_valid": true, "has_typo": false },
      "disposable": { "is_disposable": false },
      "role": { "is_role_account": true },
      "mx": { "has_mx": true, "records": ["mx.company.com"], "accepts_mail": true },
      "smtp": { "can_connect": true, "is_deliverable": true, "is_catch_all": false, "reachability": "safe" },
      "provider": { "name": "Unknown", "type": "unknown" },
      "cached": false,
      "verified_at": "2026-02-17T12:34:56Z"
    }
  ]
}

Champs de la réponse

Champ	Type	Description
`total_count`	int	Adresses uniques dans la requête. Les doublons exacts (sensibles à la casse) sont dédupliqués avant traitement et validés une seule fois, donc ce nombre peut être inférieur au nombre d'e-mails envoyés.
`processed_count`	int	Nombre d'emails traités
`successful_count`	int	Validations terminées sans erreur
`credits_consumed`	int	Crédits déduits (validations payantes)
`free_validations`	int	Validations gratuites (jetables, fautes de frappe, erreurs SMTP)
`results`	array	Une entrée par adresse unique, dans l'ordre de première apparition. Faites correspondre les résultats à votre saisie via le champ `email`, pas par position : les doublons de votre requête n'auront pas d'entrée correspondante.

Chaque élément dans results a la même structure qu'une réponse de validation unique.

Consommation de crédits

Les crédits sont vérifiés avant le traitement du lot. Si vous n'avez pas assez de crédits pour l'ensemble du lot, la requête est rejetée avec un code 402.

Au sein du lot, les validations gratuites s'appliquent selon les mêmes règles que la validation unique :

Domaines jetables : gratuit
Fautes de frappe à haute confiance (90%+), gratuit
Erreurs de connexion SMTP : gratuit

La réponse montre la répartition exacte : credits_consumed (facturés) + free_validations (non facturés) = processed_count.

Les validations par lot exécutent jusqu'à 10 emails simultanément au sein d'une seule requête. Cela équilibre le débit par rapport aux limites de taux des serveurs SMTP. Les résultats sont retournés dans le même ordre que le tableau d'entrée, indépendamment de l'ordre de traitement.

Pour les listes de plus de 100 emails, divisez-les en plusieurs requêtes par lot. La limite de concurrence s'applique par requête : vous pouvez exécuter plusieurs requêtes par lot en parallèle depuis votre serveur.

Historique de validation

Toutes les validations (uniques et par lot) sont enregistrées dans votre historique de validation :

GET https://api.mail.land/v1/validation/history

Paramètre	Type	Défaut	Description
`cursor`	string	-	Curseur opaque issu du `nextCursor` de la page précédente. À omettre pour la première page.
`limit`	int	20	Éléments par page (max 100)
`result`	string	-	Filtre : `Deliverable`, `Risky`, `Unknown`, `Undeliverable`, `Invalid`
`from`	datetime	-	Date de début
`to`	datetime	-	Date de fin
`search`	string	-	Recherche par adresse email

Réponse de l'historique de validation

{
  "items": [
    {
      "email": "u***@example.com",
      "result": "Deliverable",
      "score": 95,
      "is_disposable": false,
      "is_role_account": false,
      "has_valid_mx": true,
      "smtp_deliverable": true,
      "provider": "Unknown",
      "was_cached": false,
      "smtp_verified": true,
      "credit_consumed": true,
      "verified_at": "2026-02-17T12:34:56Z"
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoidmFsaWRhdGlvbjp2ZXJpZmllZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

Les adresses email dans l'historique sont partiellement masquées pour la confidentialité (ex. u***@example.com).

Statistiques de validation

Obtenez des statistiques agrégées de votre utilisation de la validation :

GET https://api.mail.land/v1/validation/stats

Paramètre	Type	Défaut	Description
`from`	datetime	-	Date de début
`to`	datetime	-	Date de fin

Réponse des statistiques de validation

{
  "total_validations": 450,
  "deliverable": 320,
  "risky": 65,
  "undeliverable": 50,
  "unknown": 15,
  "deliverable_rate": 71.11,
  "risky_rate": 14.44,
  "undeliverable_rate": 11.11,
  "unknown_rate": 3.33,
  "credits_consumed": 380,
  "free_validations": 70
}

Limites

Limite	Valeur
Max d'emails par lot	100
Validations simultanées par lot	10
Timeout SMTP par email	30 secondes
Longueur max d'un email	320 caractères

Réponses d'erreur

Statut	Code	Description
`400`	`INVALID_REQUEST`	Au moins un email est requis
`400`	`CONTENT_TOO_LARGE`	Le lot dépasse 100 emails
`402`	`INSUFFICIENT_CREDITS`	Pas assez de crédits pour le lot

Bonnes pratiques

Validez avant d'importer : exécutez une validation par lot sur les nouvelles listes d'abonnés avant de les importer pour éviter les pics de rebonds.
Filtrez par résultat : n'importez que les emails Deliverable. Traitez les emails Risky avec prudence et évitez entièrement les Undeliverable.
Vérifiez les suggestions de fautes : lorsque syntax.has_typo est true, présentez la syntax.suggestion à l'utilisateur pour confirmation avant l'envoi.
Utilisez lors de l'inscription : validez les emails dans votre flux d'inscription avec la validation unique pour empêcher les mauvaises adresses d'entrer dans votre système.
Surveillez l'utilisation des crédits : vérifiez /validation/credits pour suivre la consommation et planifier les mises à niveau avant d'atteindre votre limite de quota.

Prochaines étapes

Validation d'un email unique : validation en temps réel pour les adresses individuelles
Suppressions : gérez les listes de suppression
Préchauffage IP : préchauffez les domaines avec des listes propres et validées

Validation par lot

Authentification

Valider un lot

Réponse

Champs de la réponse

Consommation de crédits

Concurrence

Historique de validation

Statistiques de validation

Limites

Réponses d'erreur

Bonnes pratiques

Prochaines étapes

Sur cette page

Validation par lot

AuthentificationCopier le lien de la section

Valider un lotCopier le lien de la section

RéponseCopier le lien de la section

Champs de la réponseCopier le lien de la section

Consommation de créditsCopier le lien de la section

ConcurrenceCopier le lien de la section

Historique de validationCopier le lien de la section

Statistiques de validationCopier le lien de la section

LimitesCopier le lien de la section

Réponses d'erreurCopier le lien de la section

Bonnes pratiquesCopier le lien de la section

Prochaines étapesCopier le lien de la section

Sur cette page

Authentification

Valider un lot

Réponse

Champs de la réponse

Consommation de crédits

Concurrence

Historique de validation

Statistiques de validation

Limites

Réponses d'erreur

Bonnes pratiques

Prochaines étapes