Vérifier un email

Soumettre un job

POST /api/verify réserve le coût, met le job en file et renvoie 202 Accepted avec un job_uuid. La réponse pose un en-tête Location avec l'URL d'interrogation et un Retry-After tant que le job tourne.

curl -X POST https://api.pricklymails.com/api/verify \
  -H "Authorization: Bearer pm_live_votre_cle" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: commande-1234" \
  -d '{ "email": "quelquun@example.com" }'

Passez un en-tête Idempotency-Key optionnel pour sécuriser les retries : la même clé rejoue le job d'origine au lieu d'en facturer un nouveau (la réponse porte alors Idempotent-Replayed: true).

Interroger le résultat

GET /api/verify/{uuid} renvoie le job et ses résultats par contrôle, limités à votre compte. Il continue de poser Retry-After jusqu'à ce que le job atteigne un statut terminal (completed, failed ou canceled).

Une fois completed, le résultat porte le verdict, le score, la recommandation d'action et le résultat par contrôle :

{
    "status": "completed",
    "verdict": "risky",
    "score": 76,
    "recommendation": "send",
    "reason": "accept_all_provider",
    "checks": {
        "syntax": { "status": "valid" },
        "mx": { "status": "valid" },
        "smtp": { "status": "skipped" },
        "disposable": { "status": "valid" },
        "role": { "status": "valid" },
        "catchall": { "status": "skipped" }
    }
}

recommendation traduit le verdict honnête en action pour le nettoyage de liste : remove, send ou review (voir Batches).

Les contrôles

Chaque adresse passe par les contrôles que votre clé active :

• syntax : format RFC 5322.
• mx : le domaine a des serveurs de mail utilisables (un MX absent, null, parké ou inactif échoue ici).
• smtp : la boîte accepte le courrier (sonde de délivrabilité).
• disposable : un fournisseur jetable connu, détecté sur le domaine de l'adresse ou son serveur de mail.
• role : une adresse de rôle comme info@ ou support@.
• free : un webmail gratuit.
• catchall : le domaine accepte n'importe quelle adresse.

La détection de fautes de frappe s'exécute toujours, quels que soient les contrôles activés par votre clé : quand une faute probable est trouvée, la réponse renvoie une correction suggérée.

Verdict et score

Le résultat porte un verdict de délivrabilité (valid, invalid, risky, unknown) et un score de qualité de 0 à 100. Quand une faute est détectée, la réponse renvoie une suggestion (par exemple quelquun@gmial.com suggère quelquun@gmail.com).