SpamTest.pl
API

API dla deweloperów

Trzy wywołania: utwórz test, wyślij maila, odczytaj wynik. JSON, klucz w nagłówku, OpenAPI do wygenerowania klienta.

Swagger / OpenAPI → Pobierz klucz API

Uwierzytelnianie

Nagłówek X-API-Key (lub Authorization: Bearer). Klucz tworzysz w panelu; bez klucza działają limity darmowe per IP.

curl -X POST https://dev.spamtest.pl/api/v1/tests \
  -H "X-API-Key: st_..." -H "Content-Type: application/json" \
  -d '{"lang":"pl","placement":false}'

{ "token":"k7m2xp9q4w", "address":"test-k7m2xp9q4w@dev.spamtest.pl",
  "url":"https://dev.spamtest.pl/t/k7m2xp9q4w", "seed_addresses":[] }

Przebieg testu

  1. POST /api/v1/tests → token i adres test-<token>@spamtest.pl (opcjonalnie seed_addresses dla inbox placement).
  2. Wyślij wiadomość na ten adres (i adresy seed) ze swojego systemu.
  3. GET /api/v1/tests/{token} — status waiting → received → done; wynik, werdykt, findings z tytułem i poprawką w wybranym języku, pełne fakty.
curl https://dev.spamtest.pl/api/v1/tests/k7m2xp9q4w -H "X-API-Key: st_..."
{ "status":"done", "score":91.0, "verdict":"inbox",
  "result": { "findings":[{"key":"dmarc_p_none","severity":"minor","points":3,"title":"…","fix":"…"}],
              "facts": { "envelope":{…}, "rspamd":{"auth":{"spf":"pass","dkim":"pass","dmarc":"pass"}}, … } } }

Endpointy

EndpointOpisKlucz
POST /api/v1/testsNowy test; z kluczem bez limitu dziennego, placement: true wymaga kredytuopcjonalny
GET /api/v1/tests/{token}Status i raport testu—
GET /api/v1/domain/{domain}Audyt DNS domeny (SPF, DKIM, DMARC, MX, MTA-STS, TLS-RPT, BIMI, DBL); cache 10 minopcjonalny
GET /api/v1/blacklist/{ip}Sprawdzenie IP na 8 DNSBL + FCrDNSopcjonalny

Limity

Free: 3 testy/dzień i 30 sprawdzeń DNS per IP. Plany: wg cennika; przekroczenie zwraca 429 z used/limit. Wyniki testów są dostępne 90 dni.

Integracja z CI/CD

Najprostszy strażnik regresji dostarczalności: po deployu wyślij mail transakcyjny na adres testowy i przerwij pipeline, gdy wynik spadnie poniżej progu.

# GitHub Actions / any CI — fail the build when the deliverability score drops
TOKEN=$(curl -s -X POST https://dev.spamtest.pl/api/v1/tests -H "X-API-Key: $SPAMTEST_KEY" | jq -r .token)
python send_test_mail.py "test-$TOKEN@dev.spamtest.pl"
sleep 20
SCORE=$(curl -s https://dev.spamtest.pl/api/v1/tests/$TOKEN | jq -r .score)
[ "${SCORE%.*}" -ge 85 ] || { echo "deliverability score $SCORE < 85"; exit 1; }