API reference

Integrate SPF Pletter with your own tools

Every route below is documented with real request/response examples. The same endpoints — with exact schemas and try-it-out — are in the interactive OpenAPI reference at /api/py/docs.

Open interactive OpenAPI docs

Authentication

Server-to-server calls use an API key in the x-api-key header. Create one from Profile → API keys once signed in — the plaintext key is shown once at creation; only its hash is stored, so revoke and create a new one if you lose it.

curl -H "x-api-key: YOUR_KEY" \
  "https://your-deployment/api/py/lookups/example.com"

Rate limits

Every endpoint below is limited per caller. Exceeding it returns 429 with a Retry-After header.

Endpoint	Default limit
GET /api/py/dns/{record_type}, GET /api/py/lookups/{domain}	60/min
GET /api/py/flatten-preview	20/min
GET /api/py/lookups-preview	20/min
POST /api/py/contact	5/min

Anonymous: flatten preview

No auth required. Flattens a domain's SPF record and returns recognized senders, warnings, and the post-flatten lookup count. A domain publishing more than one SPF record is a permerror with nothing to flatten: that returns 400 with error set to multiple_spf_records and the colliding records in spf_records.

GET /api/py/flatten-preview?domain=example.com

{
  "domain": "example.com",
  "flattened_spf": "v=spf1 ip4:... -all",
  "lookup_count": 3,
  "recognized": [...],
  "warnings": []
}

API key: DNS resolve

Resolve any supported record type directly. record_type is one of SPF, TXT, A, AAAA, MX, NS, CNAME. If a domain publishes more than one SPF record it's a permerror — multiple_records is true and lookup_count is 0.

GET /api/py/dns/SPF?domain=example.com
x-api-key: YOUR_KEY

{
  "record_type": "SPF",
  "domain": "example.com",
  "spf_records": ["v=spf1 ..."],
  "lookup_count": 1,
  "multiple_records": false
}

API key: lookup tree

Same computation as the anonymous preview, but calls made with an API key get recorded as lookup history against that key's org — prefer this for integrations that want their usage tracked.

GET /api/py/lookups/example.com
x-api-key: YOUR_KEY

Everything else

Routes under /api/py/orgs, /api/py/monitored, /api/py/keys, and /api/py/admin/* back the SPF Pletter dashboard itself. They're session-cookie-only today — not part of the stable integration surface documented here.