API de test antispam : e-mail,
boîte de réception et domaine

Démarrage rapide

Trois appels. Sans clé, sans compte, sans inscription. Deux requêtes et un e-mail. Le troisième appel n’est nécessaire que parce que l’analyse prend quelques secondes.

1. Réserver une adresse

   Envoyez une requête POST au point de terminaison de la boîte de réception. Vous recevez une adresse qui accepte exactement un message et expire au bout d’une heure, ainsi que le slug servant de clé pour tout le reste.

   Requête

   # 1. reserve a single-use address
   curl -sX POST 'https://email-spam-tester.com/api/v1/inbox?lang=en'

   Réponse

   {
     "address": "test-<slug>@t.email-spam-tester.com",
     "slug": "<slug>",
     "expires_at": "2026-01-01T12:00:00Z"
   }

2. Lui envoyer le message réel

   Via SMTP, depuis la plateforme qui enverra la campagne. La moitié des contrôles lisent les en-têtes ajoutés par votre plateforme d’envoi, donc un message composé à la main mesure autre chose.

   Requête

   # 2. send your message to that address, from your own platform
   To: test-<slug>@t.email-spam-tester.com

3. Interroger le statut, puis consulter le rapport

   Le point de terminaison de statut ne représente que quelques centaines d’octets et vous indique si le rapport complet peut déjà être récupéré. Le rapport lui-même compte plusieurs milliers de lignes.

   Requête

   # 3. poll
   curl -s 'https://email-spam-tester.com/api/v1/tests/<slug>/status'

   Réponse

   {
     "slug": "<slug>",
     "analysis_status": "checks_ready",
     "ai_status": "running",
     "checks_done": 42,
     "checks_total": 42
   }

   Requête

   # 4. read the report once analysis_status is checks_ready
   curl -s 'https://email-spam-tester.com/api/v1/tests/<slug>'

   Réponse

   {
     "report_url": "https://email-spam-tester.com/t/<slug>",
     "score_ours": 86.4,
     "score_compat": 9.2,
     "subscores": {"auth": 100.0, "infra_spam": 78.1, "content": 92.0, "compliance": 75.0},
     "complete": true,
     "checks": [
       {
         "id": "auth.dmarc",
         "status": "warn",
         "title": "DMARC result",
         "summary": "DMARC passes, but the policy is p=none.",
         "weight_ours": -4.0,
         "evidence": {"policy": "none", "aligned": "dkim"},
         "citations": {"standards": [{"title": "RFC 9989 §4.7", "quote": "..."}]}
       }
     ],
     "fixes": [
       {"id": "dmarc-enforce", "gain_ours": 4.0, "gain_compat": 0.0,
        "fix": {"title": "Move DMARC to quarantine", "severity": "medium"}}
     ]
   }

Réservez une adresse, envoyez le message que vous étiez sur le point d’envoyer à votre liste, puis consultez le rapport. Tout ce que la page affiche se trouve dans le JSON, y compris le score, les 42 contrôles avec leurs éléments de preuve et la section de la norme sur laquelle repose chaque constat.

Les 100 000 premiers rapports sont gratuits, sans clé ni compte. Si vous connectez un agent plutôt qu’un script, le serveur MCP est plus adapté que l’interrogation périodique.

Points de terminaison

Adresse de base https://email-spam-tester.com. Toutes les réponses sont au format JSON.

Démarrage rapide

1. Créez un test

   Envoyez une requête POST au point de terminaison de placement. Vous obtenez un marqueur et les boîtes de réception de test.

   Requête

   # 1. create a test
   curl -sX POST 'https://email-spam-tester.com/api/v1/placement' \
     -H 'Content-Type: application/json' \
     -d '{"public_results_accepted":true}'

   Réponse

   {
     "slug": "<slug>",
     "marker": "est-3f9a1c7e2b4d6a80c5e1f2d3",
     "status": "waiting",
     "deadline": "2026-10-31T12:30:00Z",
     "poll_after_seconds": 60,
     "results": [
       {"address": "<seed>", "provider": "gmail", "kind": "Gmail",
        "placement": "pending", "observed_at": null}
     ],
     "fleet": {
       "status": "observing",
       "results": [
         {"address": "<mailbox>", "provider": "yahoo", "available": true,
          "placement": "pending", "coverage": "pending"}
       ]
     }
   }

2. Envoyez un message à chaque boîte

   Placez le marqueur dans l’objet et envoyez le message depuis votre plateforme habituelle, à toutes les adresses en une seule fois.

   Requête

   # 2. one message to every address, with the marker in the subject
   Subject: October invoice est-3f9a1c7e2b4d6a80c5e1f2d3
   To: <seed>, <mailbox>, ...

3. Interrogez les dossiers

   Chaque adresse est renseignée avec son fournisseur et son dossier. Interrogez jusqu’à ce que le statut ne soit plus waiting.

   Requête

   # 3. poll for the folders
   curl -s 'https://email-spam-tester.com/api/v1/placement/<slug>'

   Réponse

   {
     "status": "complete",
     "received": 2,
     "total": 2,
     "results": [
       {"address": "<seed>", "provider": "gmail", "kind": "Gmail",
        "placement": "primary", "observed_at": "2026-10-31T12:04:11Z"},
       {"address": "<seed>", "provider": "gmail", "kind": "Google Workspace",
        "placement": "promotions", "observed_at": "2026-10-31T12:04:11Z"}
     ],
     "fleet": {
       "status": "finished",
       "results": [
         {"address": "<mailbox>", "provider": "yahoo", "available": true,
          "placement": "inbox", "coverage": "ok"},
         {"address": "<mailbox>", "provider": "outlook", "available": true,
          "placement": "spam", "coverage": "ok"}
       ]
     }
   }

Points de terminaison

Démarrage rapide

1. Effectuez une requête GET

   Indiquez le domaine. ip ajoute vos adresses d’envoi, et selector indique les sélecteurs DKIM à lire.

   Requête

   curl -s 'https://email-spam-tester.com/api/v1/infra/check?domain=example.com&selector=mail&diff=true'

2. Lisez le verdict

   ok est la réponse destinée à un script, et sections indique quelle partie a échoué.

   Réponse

   {
     "id": "ir_01JB8Y4T2M6K9QZ7H3V5N1XWDA",
     "domain": "example.com",
     "checked_at": "2026-10-31T12:00:00Z",
     "ok": false,
     "status": "fail",
     "score": 78,
     "coverage": {"answered": 7, "total": 8},
     "ips": [{"ip": "203.0.113.5", "sources": ["mx", "spf"], "managed": false}],
     "sections": {
       "dkim": {"status": "pass", "core": true, "findings": [], "data": {}},
       "ptr": {"status": "fail", "core": true, "findings": [], "data": {}}
     },
     "not_checked": [
       {"check": "dkim_signature", "reason": "needs_a_message"},
       {"check": "alignment", "reason": "needs_a_message"}
     ],
     "diff": {
       "baseline": {"id": "ir_01JB2...", "checked_at": "2026-10-24T12:00:00Z"},
       "first_run": false,
       "changed": true,
       "worsened": true,
       "status_from": "pass",
       "score_from": 100,
       "changes": [
         {"path": "dkim.key.mail.sha256", "section": "dkim", "kind": "removed",
          "severity": "critical", "effect": "worsened", "from": "9f2c...", "to": null}
       ],
       "not_compared": [
         {"path": "blocklist_ip.203.0.113.5.bl.spamcop.net.listed", "reason": "lookup_failed"}
       ]
     }
   }

3. Ajoutez-la à cron

   Avec diff=true, chaque exécution est comparée à la précédente, et jq transforme la réponse en code de sortie.

   Requête

   # exits non-zero if the domain is broken or its setup changed
   curl -s 'https://email-spam-tester.com/api/v1/infra/check?domain=example.com&selector=mail&diff=true' \
     | jq -e '.ok and (.diff.changed | not)'

Lecture de la réponse

Une vérification terminée renvoie 200, et le verdict se trouve dans le corps. status est le pire état des sections requises : spf, dkim, dmarc, ptr, blocklist_ip, blocklist_domain, mx et smtp. unknown dans une section requise compte comme warn. ok vaut true lorsque status est pass ou warn. score va de 0 à 100 pour les sections requises ayant répondu, et vaut null lorsque les erreurs et les états unknown laissent moins de la moitié de la pondération applicable. mta_sts, tls_rpt, bimi, dnssec, dane, ns et registration sont indiqués et comparés, mais n’ont aucun effet sur ok ou score.

Une section peut être pass, warn, fail, error (nous n’avons pas pu effectuer la vérification), unknown (trop peu d’informations pour conclure) ou skipped (ne s’applique pas). skipped n’a aucun effet sur le résultat, et la raison se trouve dans not_checked. dkim_signature et alignment sont toujours présents, car ils nécessitent un message réel.

Ce que changent ip et selector

PTR et les listes de blocage concernent les adresses, une exécution en a donc besoin. Elle utilise les valeurs ip que vous transmettez. S’il n’y en a aucune, elle en prend jusqu’à quatre depuis vos hôtes MX et depuis les termes ip4: et ip6: à adresse unique de l’enregistrement SPF racine. Les adresses d’un fournisseur de messagerie connu sont indiquées comme managed et ne sont pas vérifiées, et s’il ne reste rien, ptr et blocklist_ip répondent skipped. Un selector ne peut pas être lu depuis DNS, une exécution essaie donc le vôtre, ceux trouvés par vos exécutions précédentes et une liste de noms courants. Ne rien trouver ne prouve rien, et dkim répond unknown. Si vous envoyez depuis votre propre serveur, transmettez les deux.

Ce qui a changé

Chaque entrée de diff.changes comporte path, kind (added, removed, changed), severity (critical, warning, info) et effect (worsened, improved, neutral). Seuls critical et warning définissent diff.changed, de sorte qu’une clé DKIM remplacée par rotation et de même longueur, une nouvelle adresse MX ou un certificat renouvelé ne fait pas échouer la ligne cron. diff.worsened suit l’effet de toute modification. Lors d’une première exécution, il n’y a rien à comparer, et diff.first_run l’indique.

Une référence est toujours l’une de vos propres exécutions, donc la vérification du domaine par quelqu’un d’autre entre deux de vos exécutions ne masque rien. Tout ce que nous n’avons pas pu lire cette fois-ci est placé dans diff.not_compared avec sa dernière valeur connue conservée, ce qui signifie qu’une modification effectuée pendant une indisponibilité apparaît dès que la recherche fonctionne à nouveau. Une exécution avec un ip ou un selector différent reste dans la même série, et ce qu’elle n’a pas demandé n’est pas comparé non plus.

Pourquoi une vérification planifiée doit utiliser une clé

Sans clé, votre historique appartient à un hachage avec clé de votre adresse IP, il prend donc fin lorsque l’adresse change, et les personnes derrière une même adresse le partagent : l’exécution d’un collègue déplace votre référence. Avec une clé API personnelle dans Authorization: Bearer, l’historique suit la clé. Les exécutions avec une clé sont conservées pendant 365 jours et ne sont accessibles qu’avec cette clé. Les exécutions sans clé sont conservées pendant 30 jours et sont accessibles à toute personne possédant leur id.

6 requêtes par minute et 50 par jour par IP, ou 30 et 500 par clé. Au-delà, la réponse est 429 avec Retry-After. Une requête identique dans un délai de 60 secondes provient d’un cache, porte la mention cached: true, n’enregistre aucune exécution et n’est pas comptabilisée. La lecture des exécutions stockées autorise 120 requêtes par minute et par client. 503 avec Retry-After signifie que trop de vérifications sont en cours ou, lors de la lecture des exécutions stockées, que le stockage est indisponible. 401 indique une clé incorrecte. 422 contient detail.code: invalid_domain, invalid_ip, invalid_selector, invalid_check, invalid_since, unknown_baseline ou account_required.

Points de terminaison

Démarrage rapide

1. Choisir une vérification

   Choisissez l’outil dans la liste ci-dessous et transmettez-lui le domaine, l’adresse ou l’IP qu’il demande.

   Requête

   curl -s 'https://email-spam-tester.com/api/v1/tools/spf?domain=example.com'

2. Lire le statut et les résultats

   Chaque outil renvoie un statut et ses résultats. Les champs suivants dépendent de l’outil.

   Réponse

   {
     "tool": "spf",
     "query": {"domain": "example.com"},
     "checked_at": "2026-10-31T12:00:00Z",
     "duration_ms": 412,
     "status": "fail",
     "findings": [
       {"code": "spf.too_many_lookups", "level": "fail",
        "params": {"limit": 10, "count": 12},
        "message": "RFC 7208 §4.6.4 allows at most 10 DNS lookups, and this record needs 12, so receivers return permerror."}
     ],
     "record": "v=spf1 include:_spf.example.net ~all",
     "lookups": {"count": 12, "limit": 10, "void": 0}
   }

Points de terminaison