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

  1. Allez dans Tableau de bord > Cles API
  2. Cliquez sur le bouton IPs a cote de votre cle
  3. Entrez une adresse IP ou plage CIDR par ligne
  4. 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

  1. Allez dans Tableau de bord > Webhooks
  2. Entrez l'URL de votre endpoint (HTTPS recommande)
  3. 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"
  }
}