Mailtest.me

Documentation API

L'API REST Mailtest.me permet d'intégrer la vérification d'emails et le test antispam dans vos propres outils, scripts et pipelines.

Introduction

L'API est réservée aux abonnés à partir du plan Pro (50 vérifications/jour). Toutes les réponses sont en JSON. L'URL de base de toutes les requêtes est :

https://mailtest.me

Deux fonctionnalités sont exposées : la vérification d'adresses email et le test antispam (délivrabilité). Chaque fonctionnalité consomme son propre quota quotidien.

Authentification

Toutes les requêtes API doivent inclure votre clé API dans le header HTTP X-API-Key :

X-API-Key: mt_votre_cle_api

Vous pouvez générer votre clé depuis votre page compte. La clé complète n'est affichée qu'une seule fois, à sa création : conservez-la en lieu sûr.

  • 401 — clé manquante ou invalide
  • 403 — abonnement insuffisant (plan Pro minimum requis)

Vérification d'email

Vérifie une adresse email en trois étapes : syntaxe (RFC 5322), DNS (enregistrements MX), et SMTP (poignée de main avec le serveur). Retourne un score de confiance de 0 à 100. Chaque appel est décompté de votre quota de vérifications quotidien.

Vérifier une adresse

POST /api/v1/check
Headers
X-API-Key: mt_votre_cle_api Content-Type: application/json
Body (JSON)
{ "email": "test@example.com" }
Réponse 200
{ "email": "test@example.com", "checks": { "syntax": { "status": "valid", "message": "Syntaxe valide", "detail": "Format RFC 5322 OK" }, "dns": { "status": "valid", "message": "Serveurs MX trouvés", "mx_records": [ { "host": "aspmx.l.google.com", "priority": 1 } ] }, "smtp": { "status": "valid", "message": "Serveur SMTP répond", "server": "aspmx.l.google.com", "response_code": 220 } }, "overall_score": 95, "is_valid": true, "checked_at": "2026-08-12T12:00:00.000000" }
Erreurs
401 — Clé API manquante ou invalide 403 — Abonnement insuffisant (plan Pro minimum requis) 422 — Adresse email invalide 429 — Limite quotidienne de vérifications atteinte

Test antispam

Le test antispam mesure la délivrabilité de vos emails (newsletters, emails transactionnels). L'API génère une adresse email jetable unique ; vous lui envoyez votre email ; Mailtest.me l'analyse (SPF, DKIM, DMARC, SpamAssassin, contenu analysé par IA) et vous retourne un score sur 100 avec un rapport détaillé.

Chaque appel de création est décompté de votre quota de tests antispam quotidien, indépendant du quota de vérifications d'emails (voir Limites).

Principe de fonctionnement

1
Créez un test — appelez POST /api/v1/spam-test. Vous recevez en retour une adresse email jetable unique du type spamtest-a1b2c3d4@spamtest.mailtest.me. Chaque appel crée un test neuf : ne réutilisez pas une adresse d'un test précédent.
2
Envoyez votre email — expédiez la newsletter ou l'email transactionnel à tester vers l'adresse jetable, exactement comme vous l'enverriez à un destinataire réel (même serveur SMTP, même contenu). L'analyse démarre automatiquement dès réception (statut analyzing).
3
Récupérez le résultat — interrogez GET /api/v1/spam-test/{id} toutes les 3 secondes jusqu'à obtention du statut done. Le score et le rapport complet sont alors disponibles.
Statuts d'un test
Statut Description
waitingEn attente de réception de l'email
analyzingEmail reçu, analyse en cours
doneAnalyse terminée, résultat disponible
errorÉchec de l'analyse

Créer un test

POST /api/v1/spam-test

Crée un nouveau test antispam et retourne l'adresse jetable. Aucun body n'est requis.

Headers
X-API-Key: mt_votre_cle_api
Réponse 200
{ "id": "a1b2c3d4", "address": "spamtest-a1b2c3d4@spamtest.mailtest.me", "status": "waiting", "remaining": 4 }

remaining : nombre de tests antispam encore disponibles aujourd'hui pour votre compte.

Erreurs
401 — Clé API manquante ou invalide 403 — Abonnement insuffisant (plan Pro minimum requis) 429 — Limite quotidienne de tests antispam atteinte

Envoyer l'email de test

Cette étape ne passe pas par l'API : envoyez simplement votre email à l'adresse jetable retournée à l'étape précédente, depuis le serveur ou le service (ESP, SMTP relais, newsletter) que vous souhaitez évaluer.

  • L'adresse jetable n'accepte que le premier email reçu : n'en envoyez qu'un seul.
  • L'analyse démarre automatiquement à réception et prend généralement quelques secondes.
  • Conservez l' id du test pour interroger le résultat.

Récupérer le résultat

GET /api/v1/spam-test/{id}

Retourne le statut courant du test et, lorsque l'analyse est terminée, le rapport complet. Le test doit avoir été créé avec la même clé API.

Headers
X-API-Key: mt_votre_cle_api
Réponse 200 — analyse en cours
{ "id": "a1b2c3d4", "address": "spamtest-a1b2c3d4@spamtest.mailtest.me", "status": "analyzing", "score": null, "subject": "Votre campagne de juillet", "sender": "newsletter@example.com", "result": null }
Réponse 200 — analyse terminée
{ "id": "a1b2c3d4", "address": "spamtest-a1b2c3d4@spamtest.mailtest.me", "status": "done", "score": 87, "subject": "Votre campagne de juillet", "sender": "newsletter@example.com", "result": { "score": 87, "grade": "Excellent", "summary": "0 problème(s) critique(s), 2 avertissement(s) sur 12 points vérifiés.", "findings": [ { "severity": "warning", "category": "DKIM", "message": "Signature DKIM absente", "explanation": "...", "solution": "..." } ], "ai": { "content_score": 82, "suggestions": [ "..." ] }, "meta": { "from": "newsletter@example.com", "sender_domain": "example.com", "sender_ip": "203.0.113.10", "spamassassin_score": 1.8 } } }
Erreurs
401 — Clé API manquante ou invalide 403 — Plan insuffisant, ou test créé par un autre compte 404 — Test introuvable

Limites

Les quotas de vérifications d'emails et de tests antispam sont indépendants et se réinitialisent chaque jour à minuit (UTC).

Plan Vérifications / jour Tests antispam / jour Accès API
Gratuit 3 1 (par IP) Non
Starter (10/j) 10 2 Non
Pro (50/j) 50 5 Oui
Business (100/j) 100 10 Oui
Enterprise (500/j) 500 25 Oui
Note — le plan Starter (10/jour) inclut 2 tests antispam par jour via l'interface web, mais n'a pas accès à l'API. L'accès API démarre au plan Pro.

Codes d'erreur

Les erreurs suivent les conventions HTTP. Le body de la réponse contient un champ detail descriptif.

Code Description
401Clé API manquante ou invalide.
403Abonnement insuffisant (plan Pro minimum), ou tentative d'accès à un test appartenant à un autre compte.
404Ressource introuvable (identifiant de test inconnu).
422Body de requête invalide (ex : adresse email mal formée).
429Quota quotidien atteint. Le message précise lequel (vérifications ou tests antispam).
500Erreur interne. Réessayez plus tard.

Exemples

cURL

Vérification d'email
curl -X POST https://mailtest.me/api/v1/check \ -H "X-API-Key: mt_votre_cle_api" \ -H "Content-Type: application/json" \ -d '{"email": "test@example.com"}'
Test antispam — flux complet
# Étape 1 — créer le test curl -X POST https://mailtest.me/api/v1/spam-test \ -H "X-API-Key: mt_votre_cle_api" # → {"id": "a1b2c3d4", "address": "spamtest-a1b2c3d4@spamtest.mailtest.me", ...} # Étape 2 — envoyez votre email à l'adresse retournée # Étape 3 — récupérer le résultat (à répéter toutes les 3 s) curl https://mailtest.me/api/v1/spam-test/a1b2c3d4 \ -H "X-API-Key: mt_votre_cle_api"

Python

Test antispam avec polling
import time import requests BASE = "https://mailtest.me" HEADERS = {"X-API-Key": "mt_votre_cle_api"} # 1. Créer le test r = requests.post(f"{BASE}/api/v1/spam-test", headers=HEADERS) r.raise_for_status() test = r.json() print("Envoyez votre email à :", test["address"]) # 2. ... envoyez l'email depuis votre serveur SMTP ... # 3. Poller le résultat while True: time.sleep(3) r = requests.get( f"{BASE}/api/v1/spam-test/{test['id']}", headers=HEADERS, ) r.raise_for_status() data = r.json() if data["status"] in ("done", "error"): break print("Score :", data["score"], "/100")