Authentification
Toutes les requetes API necessitent une authentification via une cle API transmise dans l'en-tete Authorization.
Format de la cle API
Les cles utilisent le format sk_live_ suivi de 64 caracteres hexadecimaux :
sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789...
Utiliser votre cle
Incluez la cle dans l'en-tete Authorization avec le schema Bearer :
cURL
curl -H "Authorization: Bearer sk_live_VOTRE_CLE" \
"https://emailkind.com/v1/classify?email=test@gmail.com"
JavaScript
const response = await fetch(
"https://emailkind.com/v1/classify?email=test@gmail.com",
{
headers: {
Authorization: "Bearer sk_live_VOTRE_CLE",
},
}
);
const data = await response.json();
Python
import requests
response = requests.get(
"https://emailkind.com/v1/classify",
params={"email": "test@gmail.com"},
headers={"Authorization": "Bearer sk_live_VOTRE_CLE"}
)
data = response.json()
PHP
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => "https://emailkind.com/v1/classify?email=test@gmail.com",
CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_live_VOTRE_CLE"],
CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
Go
req, _ := http.NewRequest("GET", "https://emailkind.com/v1/classify?email=test@gmail.com", nil)
req.Header.Set("Authorization", "Bearer sk_live_VOTRE_CLE")
resp, err := http.DefaultClient.Do(req)
Ruby
uri = URI("https://emailkind.com/v1/classify?email=test@gmail.com")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer sk_live_VOTRE_CLE"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
Obtenir une cle par programmation
Les agents IA et les scripts peuvent obtenir leur propre cle sans navigateur. Deux requetes, fondees sur le controle d'une boite email.
Etape 1 — demander un code
POST /v1/signup
Content-Type: application/json
{"email": "vous@exemple.com", "lang": "fr"}
{
"success": true,
"request_id": "req_a1b2c3d4e5f6",
"status": "verification_sent",
"expires_in": 900,
"next": "POST /v1/signup/confirm"
}
Un code de 8 caracteres est envoye a l'adresse. Rien n'est enregistre a ce stade : aucun compte n'existe avant le retour du code, donc une inscription abandonnee ne laisse aucune trace.
La reponse est identique selon que l'adresse possede deja un compte ou non — l'endpoint ne permet donc pas de savoir qui en a un.
lang est optionnel (en ou fr) et ne change que la langue de l'email.
Etape 2 — l'echanger contre une cle
POST /v1/signup/confirm
Content-Type: application/json
{"email": "vous@exemple.com", "code": "K7M2QXAB"}
{
"success": true,
"request_id": "req_a1b2c3d4e5f6",
"api_key": "sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
"plan": "free",
"monthly_limit": 100,
"burst_limit": 10,
"docs": "https://emailkind.com/docs/getting-started"
}
Le code est insensible a la casse, et les espaces ou tirets qu'il contient sont ignores. Si l'adresse n'a pas encore de compte, il est cree et deja verifie — le code a prouve la boite email, il n'y a donc pas d'email de verification separe.
La cle est une cle live normale, identique a celle creee dans le tableau de bord. Elle est renvoyee une seule fois. Stockez-la comme un secret : contrairement a une cle du tableau de bord, celle-ci passe par vos logs.
Limites et erreurs
| Limite | Valeur | |---|---| | Validite du code | 15 minutes | | Tentatives par code | 5, puis l'inscription est annulee | | Inscriptions demarrees | 5 par heure et par IP | | Codes envoyes | 3 par heure et par adresse |
| Code | Statut | Signification |
|---|---|---|
| INVALID_BODY | 400 | Corps non JSON, ou champ requis manquant |
| INVALID_EMAIL | 400 | Adresse mal formee ou sans TLD valide |
| DISPOSABLE_EMAIL | 400 | Le domaine est un fournisseur d'email jetable |
| UNDELIVERABLE_EMAIL | 400 | Le fournisseur d'email a rejete l'adresse |
| INVALID_CODE | 400 | Code incorrect, expire, ou jamais emis |
| KEY_LIMIT_REACHED | 409 | Le compte detient deja le maximum de cles de son plan |
| RATE_LIMITED | 429 | Trop d'inscriptions depuis cette IP, ou trop de codes vers cette adresse |
| TOO_MANY_ATTEMPTS | 429 | Cinq codes errones ; l'inscription a ete annulee |
| SIGNUP_UNAVAILABLE | 503 | Inscription momentanement indisponible ; utilisez le formulaire web ou reessayez |
Un code expire et un code jamais emis partagent INVALID_CODE : une fois l'enregistrement expire, plus rien ne permet de les distinguer.
Les comptes crees ainsi n'ont pas de mot de passe
L'inscription a prouve une boite email, pas un mot de passe : le compte demarre donc sans. Pour vous connecter au tableau de bord, utilisez Mot de passe oublie sur la page de connexion pour en definir un — cela fonctionne normalement sur ces comptes.
Gestion des cles
Vous pouvez gerer vos cles API depuis le Tableau de bord :
- Creer de nouvelles cles avec des noms descriptifs (ex. "Production", "Staging")
- Revoquer les cles compromises ou inutilisees
- Consulter les prefixes et dates de derniere utilisation
Bonnes pratiques de securite
| A faire | A eviter | |---|---| | Stocker les cles dans des variables d'environnement | Commiter les cles dans le controle de version | | Utiliser des cles differentes par environnement | Partager les cles entre applications | | Revoquer les cles inutilisees | Logger les cles completes | | Renouveler les cles periodiquement | Exposer les cles cote client |
Limites de cles par plan
| Plan | Cles API max | |---|---| | Gratuit | 1 | | Starter | 3 | | Growth | 5 | | Scale | 10 |
Liste blanche d'IPs
Vous pouvez restreindre chaque cle API a des adresses IP specifiques pour renforcer la securite. Les requetes provenant d'IPs non autorisees seront rejetees avec une reponse 403 Forbidden.
Configuration
- Allez dans Tableau de bord > Cles API
- Cliquez sur le bouton IPs a cote de votre cle
- Entrez une adresse IP ou plage CIDR par ligne
- Cliquez sur Enregistrer les restrictions IP
Formats supportes
| Format | Exemple | Description |
|---|---|---|
| IPv4 | 203.0.113.1 | Adresse IP unique |
| IPv6 | 2001:db8::1 | Adresse IPv6 unique |
| CIDR | 10.0.0.0/8 | Plage IP (tout 10.x.x.x) |
| CIDR v6 | 2001:db8::/32 | Plage IPv6 |
Laissez la liste vide pour autoriser les requetes depuis n'importe quelle IP (par defaut).
Reponse d'erreur
{
"success": false,
"error": {
"code": "IP_NOT_ALLOWED",
"message": "Your IP address is not in the allowlist for this API key"
}
}
Webhooks
EmailKind peut notifier votre application via des webhooks lorsque la classification d'un domaine change. Utile pour garder vos donnees a jour sans polling.
Configuration
- Allez dans Tableau de bord > Webhooks
- Entrez l'URL de votre endpoint (HTTPS recommande)
- Copiez et stockez le secret de signature en securite
Evenements
| Evenement | Description |
|---|---|
| domain.changed | Le type de fournisseur d'un domaine a change depuis la derniere classification |
Format du payload
{
"event": "domain.changed",
"timestamp": "2025-01-15T10:30:00Z",
"data": {
"domain": "example.com",
"old_type": "business",
"new_type": "disposable",
"provider_id": "mailinator",
"provider_name": "Mailinator"
}
}
Verification des signatures
Chaque requete webhook inclut un en-tete X-EmailKind-Signature contenant une signature HMAC-SHA256 du corps du payload :
X-EmailKind-Signature: sha256=5d41402abc4b2a76b9719d911017c592...
Verifiez la signature avec votre secret :
import hmac, hashlib
def verify_signature(payload, signature, secret):
expected = "sha256=" + hmac.new(
secret.encode(), payload, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature)
Reponse d'erreur
Si l'authentification echoue, vous recevrez une reponse 401 Unauthorized :
{
"success": false,
"request_id": "req_abc123",
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
}