SpamTest.pl
API

API for developers

Three calls: create a test, send an email, read the result. JSON, key in a header, OpenAPI to generate a client.

Swagger / OpenAPI → Get an API key

Authentication

Header X-API-Key (or Authorization: Bearer). Create keys in the dashboard; without a key the free per-IP limits apply.

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

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

Test flow

  1. POST /api/v1/tests → token and address test-<token>@spamtest.pl (optionally seed_addresses for inbox placement).
  2. Send a message to that address (and the seed addresses) from your system.
  3. GET /api/v1/tests/{token} — status waiting → received → done; score, verdict, findings with title and fix in the chosen language, full facts.
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"}}, … } } }

Endpoints

EndpointDescriptionKey
POST /api/v1/testsNew test; with a key no daily limit, placement: true consumes a creditoptional
GET /api/v1/tests/{token}Test status and report—
GET /api/v1/domain/{domain}Domain DNS audit (SPF, DKIM, DMARC, MX, MTA-STS, TLS-RPT, BIMI, DBL); 10-minute cacheoptional
GET /api/v1/blacklist/{ip}IP check on 8 DNSBLs + FCrDNSoptional

Limits

Free: 3 tests/day and 30 DNS checks per IP. Plans: per pricing; exceeding returns 429 with used/limit. Test results stay available for 90 days.

CI/CD integration

The simplest deliverability regression guard: after a deploy, send a transactional email to a test address and fail the pipeline when the score drops below a threshold.

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