REST API · v1

Documentation API

Intégrez la validation d'email EmailClean dans vos applications. Base URL : https://emailclean.app

Authentification

Toutes les requêtes nécessitent un header Authorization.

Authorization:Bearer ec_votre_cle_api

Obtenez votre clé sur la page tarifs ou dans votre espace compte.

Valider un email (instantané)

GET/api/v1/validate-one?email=· 1 crédit

cURL

curl "https://emailclean.app/api/v1/validate-one?email=alice@example.com" \
  -H "Authorization: Bearer ec_votre_cle_api"

JavaScript

const res = await fetch('https://emailclean.app/api/v1/validate-one?email=alice@example.com', {
  headers: { Authorization: 'Bearer ec_votre_cle_api' }
});
const data = await res.json();
// { email, status, score, mx, smtp, disposable, ... }

Python

import requests
r = requests.get(
    'https://emailclean.app/api/v1/validate-one',
    params={'email': 'alice@example.com'},
    headers={'Authorization': 'Bearer ec_votre_cle_api'}
)
print(r.json())

Réponse

{
  "email": "alice@example.com",
  "status": "valid",        // valid | risky | invalid
  "score": 95,
  "mx": true,
  "smtp": true,
  "disposable": false,
  "role_based": false,
  "free_provider": false,
  "did_you_mean": null
}

Upload CSV (traitement par lot)

POST/api/upload· multipart/form-data

Champ	Type	Requis	Description
file	File	✓	CSV ou TXT — une adresse par ligne.
webhook_url	string		URL appelée à la fin du traitement.
notify_email	string		Email de notification à la fin.
ref	string		Code partenaire affilié.

cURL

curl -X POST "https://emailclean.app/api/upload" \
  -H "Authorization: Bearer ec_votre_cle_api" \
  -F "file=@emails.csv" \
  -F "webhook_url=https://mon-site.fr/webhook" \
  -F "notify_email=moi@example.com"

JavaScript

const form = new FormData();
form.append('file', fileBlob, 'emails.csv');
form.append('webhook_url', 'https://mon-site.fr/webhook');

const res = await fetch('https://emailclean.app/api/upload', {
  method: 'POST',
  headers: { Authorization: 'Bearer ec_votre_cle_api' },
  body: form,
});
const { jobId } = await res.json();

{ "jobId": "abc123def456", "emailCount": 10000, "estimatedMinutes": 8 }

Statut d'un job

GET/api/jobs/{jobId}

cURL

curl "https://emailclean.app/api/jobs/{jobId}" \
  -H "Authorization: Bearer ec_votre_cle_api"

Réponse

{
  "id": "abc123",
  "status": "completed",   // pending | processing | completed | failed
  "total": 10000,
  "processed": 10000,
  "valid_count": 8743,
  "risky_count": 412,
  "invalid_count": 845,
  "duplicate_count": 238,
  "score": 87,
  "paid": true,
  "created_at": "2025-01-15T14:30:00Z"
}

Télécharger les résultats

GET/api/download/{jobId}?type=valid&format=xlsx

Paramètre	Valeurs
type	`valid` · `risky` · `invalid` · `all`
format	`csv` · `xlsx` · `json`

curl "https://emailclean.app/api/download/{jobId}?type=valid&format=xlsx" \
  -H "Authorization: Bearer ec_votre_cle_api" \
  --output emails_valides.xlsx

Webhooks

Si vous passez un webhook_url, EmailClean envoie un POST JSON quand le job est terminé. 3 tentatives espacées de 0s, 5s, 15s en cas d'échec.

{
  "event": "job.completed",
  "jobId": "abc123",
  "status": "completed",
  "stats": {
    "total": 10000,
    "valid": 8743,
    "risky": 412,
    "invalid": 845,
    "score": 87
  },
  "downloadUrl": "https://emailclean.app/result/abc123"
}

Codes d'erreur

HTTP	Code	Description
400	bad_request	Paramètre manquant ou invalide
401	unauthorized	Clé API invalide ou absente
402	payment_required	Crédits insuffisants
404	not_found	Job introuvable
429	rate_limited	3 analyses gratuites/jour dépassées
500	server_error	Erreur interne

Limites & quotas

Sans clé API

3 uploads / IP / jour

Taille max 5 000 emails

Avec clé API

Illimité

Limité par vos crédits

/validate-one

1 crédit / appel

Max 100 req/s