API for developers

The Spamexx API: check indicators against the threat database and run messages through the spam and virus check – with an API key and a quota from your plan.

Quickstart

Three steps to your first response:

Create an API key under Settings → API keys (shown only once).
Send the key in the Authorization header.
Make a request to an endpoint – e.g. the threat lookup:

user@spamexx:~$cat quickstart.sh

curl -X POST https://api.spamexx.com/api/v1/check/lookup \
  -H "Authorization: Bearer sx_ihr_schluessel" \
  -H "Content-Type: application/json" \
  -d '{"type":"domain","value":"example.com"}'

Authentication

Every request needs an API key in the Authorization header (or X-API-Key). Create the key under Settings → API keys.

user@spamexx:~$cat header.txt

Authorization: Bearer sx_ihr_schluessel

Quota (requests/month) and rate limit (requests/minute) follow your API plan. Without a booked API plan the free tier applies. You can see your current usage under Settings → API keys.

Quota & rate limit

Each tenant has a monthly request quota and a per-minute rate limit – both from your API plan. An exhausted quota or exceeded rate is answered with 429.

Only successful (authenticated) requests count against the quota. Rejected requests (401/403/429) are not counted.

POST/api/v1/check/lookupAuth required

Threat lookup

Checks a single indicator against the Spamexx threat database and returns verdict, score and a match flag.

Request body (JSON)

Field	Description
type	Indicator type: domain, email, ip, url or hash.
value	The value to check (e.g. the domain, IP or URL).

user@spamexx:~$cat example.sh

curl -X POST https://api.spamexx.com/api/v1/check/lookup \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"domain","value":"example.com"}'

Response

user@spamexx:~$cat response.json

{
  "type": "domain",
  "value": "example.com",
  "verdict": "clean",
  "score": 0.0,
  "matched": false
}

POST/api/v1/check/messageAuth required

Content check

Runs a submitted message through the spam and virus check and returns a verdict (deliver / quarantine / reject) plus score.

For an accurate result send the full raw message with headers where possible. A minimal message without headers may score higher simply because standard headers are missing. The content is checked only transiently and never stored.

Request body (JSON)

Field	Description
raw	Full raw message (RFC 822, text or Base64) – recommended for the most accurate result.
from / to / subject / body	Alternatively individual fields if no raw message is available.
source_ip	Optional sender IP (feeds into the reputation scoring).

user@spamexx:~$cat example.sh

curl -X POST https://api.spamexx.com/api/v1/check/message \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"absender@example.com","subject":"Hallo","body":"Nachrichtentext"}'

Response

user@spamexx:~$cat response.json

{
  "verdict": "deliver",
  "score": 2.1,
  "is_spam": false,
  "is_virus": false
}

GET/api/v1/limitsAuth required

Plan limits & usage

Returns the tariff limits assigned to the API key per product line, with current usage: API quota (used/limit) and rate, Online/SaaS (domains & mailboxes used/limit, retention) and Backup/Failover. Lines that are not booked are omitted.

This call does NOT consume quota (own limit 60/min). Hard enforcement still happens on the check endpoints (HTTP 429 when exhausted) — the reported usage values are informational.

user@spamexx:~$cat example.sh

curl https://api.spamexx.com/api/v1/limits \
  -H "Authorization: Bearer $KEY"

Response

user@spamexx:~$cat response.json

{
  "tenant_id": "…",
  "period": "2026-06",
  "unlimited": false,
  "api":   { "plan": "Community", "requests": { "used": 0, "max": 5000 }, "remaining": 5000, "rate_per_min": 10 },
  "saas":  { "plan": "Enterprise", "domains": { "used": 1, "max": 50 }, "mailboxes": { "used": 6, "max": 500 }, "retention_days": 365 },
  "spool": { "plan": "Basic", "domains": { "used": 0, "max": 3 }, "spool_retention_hours": 72 }
}

Response fields

The endpoints return a generic verdict without details about the checks used.

Field	Type	Description
verdict	string	Lookup: clean / suspicious / spam. Content check: deliver / quarantine / reject.
score	number	Lookup: reputation value 0–1. Content check: aggregated check score.
matched	boolean	Lookup only: hit in the threat database.
is_spam	boolean	Content check only: classified as spam.
is_virus	boolean	Content check only: classified as a virus.

Errors

Errors come as JSON with an error field; the HTTP status shows the category.

Status	Meaning	Resolution
401	Key missing, invalid or revoked.	Check the Authorization header; create a new key if needed.
403	No active API plan.	Book an API plan (the free tier is enough).
429	Rate limit or monthly quota reached.	Retry later with backoff or raise your plan.
503	Check temporarily unavailable.	Send the request again later.

Best practices

Send the full raw message

For the most accurate content scoring send the complete message with headers (raw) – minimal fields without headers may score higher.

Cache responses

Briefly cache lookups for the same indicator to save quota.

Handle 429 gracefully

On rate limit/quota, retry with exponential backoff instead of hammering.

Protect your key

Use API keys only server-side, never embed them in the browser/client; revoke immediately if compromised.

FAQ

› Which indicator types does the lookup support?

domain, email, ip, url and hash.

› Is my submitted content stored?

No. The content is checked only transiently and never stored or logged.

› Where does my quota come from?

From your API plan (Settings → API keys). Without a booked plan the free tier applies.

› How do I create an API key?

Under Settings → API keys. For security the key is shown only once.