API di controllo spam: email,
posta in arrivo e dominio

Avvio rapido

Tre chiamate. Nessuna chiave, nessun account, nessuna registrazione. Due richieste e un'email. La terza chiamata serve solo perché l'analisi richiede alcuni secondi.

1. Riserva un indirizzo

   Invia una richiesta POST all'endpoint della casella di posta. Ricevi un indirizzo che accetta esattamente un messaggio e scade dopo un'ora, insieme allo slug su cui si basa tutto il resto.

   Richiesta

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

   Risposta

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

2. Inviagli il messaggio reale

   Tramite SMTP, dalla piattaforma che invierà la campagna. Metà dei controlli legge le intestazioni aggiunte dalla piattaforma di invio, quindi un messaggio composto a mano misura la cosa sbagliata.

   Richiesta

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

3. Interroga lo stato, quindi leggi il report

   L'endpoint di stato occupa poche centinaia di byte e indica se vale già la pena recuperare il report completo. Il report stesso si estende per diverse migliaia di righe.

   Richiesta

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

   Risposta

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

   Richiesta

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

   Risposta

   {
     "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"}}
     ]
   }

Riserva un indirizzo, invia il messaggio che stavi per inviare alla tua lista, leggi il report. Tutto ciò che mostra la pagina è nel JSON, incluso il punteggio, tutti i 42 controlli con le relative evidenze e la sezione dello standard su cui si basa ciascun risultato.

I primi 100.000 report sono gratuiti, senza chiave e senza account. Se stai configurando un agente anziché uno script, il server MCP è più adatto del polling.

Endpoint

Indirizzo base https://email-spam-tester.com. Tutto risponde in JSON.

Avvio rapido

1. Crea un test

   Esegui una richiesta POST all'endpoint di posizionamento. Riceverai un marcatore e le caselle di posta di test.

   Richiesta

   # 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}'

   Risposta

   {
     "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. Invia un messaggio a ogni casella

   Inserisci il marcatore nell'oggetto e invia il messaggio dalla tua piattaforma abituale a tutti gli indirizzi in un'unica operazione.

   Richiesta

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

3. Interroga le cartelle

   Per ogni indirizzo vengono indicati il provider e la cartella. Ripeti la richiesta finché lo stato non è più waiting.

   Richiesta

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

   Risposta

   {
     "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"}
       ]
     }
   }

Endpoint

Avvio rapido

1. Esegui una GET

   Passa il dominio. ip aggiunge i tuoi indirizzi di invio e selector specifica i selettori DKIM da leggere.

   Richiesta

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

2. Leggi il verdetto

   ok è la risposta per uno script e sections mostra quale parte ha dato errore.

   Risposta

   {
     "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. Inseriscilo in cron

   Con diff=true ogni esecuzione viene confrontata con la tua ultima esecuzione e jq trasforma la risposta in un codice di uscita.

   Richiesta

   # 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)'

Lettura della risposta

Un controllo completato restituisce 200 e il verdetto si trova nel corpo. status è lo stato peggiore delle sezioni obbligatorie: spf, dkim, dmarc, ptr, blocklist_ip, blocklist_domain, mx e smtp. unknown in una sezione obbligatoria conta come warn. ok è true quando status è pass o warn. score va da 0 a 100 sulle sezioni obbligatorie che hanno prodotto una risposta ed è null quando errori e valori unknown lasciano meno della metà del peso applicabile. mta_sts, tls_rpt, bimi, dnssec, dane, ns e registration vengono riportati e confrontati, ma non influiscono su ok o score.

Una sezione può essere pass, warn, fail, error (non è stato possibile controllarla), unknown (informazioni insufficienti) o skipped (non applicabile). skipped non influisce sul risultato e il motivo si trova in not_checked. dkim_signature e alignment sono sempre presenti, perché richiedono un messaggio reale.

Cosa cambia con ip e selector

PTR e le blocklist riguardano gli indirizzi, quindi un'esecuzione ne richiede alcuni. Usa i valori ip che fornisci. Se non ne fornisci, ne prende fino a quattro dagli host MX e dai termini ip4: e ip6: con un solo indirizzo nel record SPF radice. Gli indirizzi di un provider di posta noto vengono indicati come managed e non vengono controllati; se non resta alcun indirizzo, ptr e blocklist_ip restituiscono skipped. Un selector non può essere ricavato dal DNS, quindi un'esecuzione prova quello che fornisci, quelli trovati dalle tue esecuzioni precedenti e un elenco di nomi comuni. Non trovare nulla non dimostra nulla e dkim restituisce unknown. Se invii dal tuo server, fornisci entrambi.

Cosa è cambiato

Ogni voce in diff.changes ha un path, un kind (added, removed, changed), una severity (critical, warning, info) e un effect (worsened, improved, neutral). Solo critical e warning impostano diff.changed, quindi una chiave DKIM ruotata della stessa lunghezza, un nuovo indirizzo MX o un certificato rinnovato non causano il fallimento della riga cron. diff.worsened segue l'effetto di qualsiasi modifica. Alla prima esecuzione non c'è nulla con cui effettuare il confronto, e diff.first_run lo indica.

Una baseline è sempre una tua esecuzione, quindi il controllo del dominio da parte di qualcun altro tra due tue esecuzioni non nasconde nulla. Tutto ciò che non è stato possibile leggere questa volta viene inserito in diff.not_compared mantenendo il suo ultimo valore noto, il che significa che una modifica apportata durante un'interruzione compare non appena la ricerca torna a funzionare. Un'esecuzione con ip o selector diversi rimane nella stessa serie e anche ciò che non ha richiesto non viene confrontato.

Perché un controllo pianificato dovrebbe usare una chiave

Senza una chiave, la tua cronologia è associata a un hash con chiave del tuo indirizzo IP, quindi termina quando l'indirizzo cambia e le persone dietro lo stesso indirizzo la condividono: l'esecuzione di un collega sposta la tua baseline. Con una chiave API personale in Authorization: Bearer, la cronologia segue la chiave. Le esecuzioni con una chiave vengono conservate per 365 giorni e sono accessibili solo con quella chiave. Le esecuzioni senza chiave vengono conservate per 30 giorni e sono accessibili a chiunque disponga del loro id.

6 richieste al minuto e 50 al giorno per IP, oppure 30 e 500 per chiave. Oltre questi limiti, la risposta è 429 con Retry-After. Una richiesta identica entro 60 secondi proviene dalla cache, è contrassegnata con cached: true, non registra alcuna esecuzione e non viene conteggiata. La lettura delle esecuzioni memorizzate consente 120 richieste al minuto per client. 503 con Retry-After significa che sono in esecuzione troppi controlli oppure, durante la lettura delle esecuzioni memorizzate, che lo spazio di archiviazione non è disponibile. 401 indica una chiave errata. 422 include detail.code: invalid_domain, invalid_ip, invalid_selector, invalid_check, invalid_since, unknown_baseline o account_required.

Endpoint

Avvio rapido

1. Scegli un controllo

   Scegli lo strumento dall'elenco seguente e fornisci il dominio, l'indirizzo o l'IP richiesto.

   Richiesta

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

2. Leggi lo stato e i risultati

   Ogni strumento restituisce uno stato e i relativi risultati. I campi successivi dipendono dallo strumento.

   Risposta

   {
     "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}
   }

Endpoint