SDKs
Official libraries for Node.js and Python. Both have no dependencies and are safe by default:
- 3-second timeouts
- retries that respect
retry-afterand never run a check twice - checks that let messages through when Spamgone can't be reached
The packages are being published to npm and PyPI. Until they're there, call the API directly, as in the Quickstart.
Node.js
npm install spamgoneIt needs Node.js 18 or later, and comes with TypeScript types.
import { Spamgone } from "spamgone";
const spamgone = new Spamgone({ apiKey: process.env.SPAMGONE_API_KEY });
const check = await spamgone.checks.create({
text: "Turn $250 into $5,000 in 7 days. DM me on Telegram",
context: { content_type: "message", author: { id: "user_8412" } },
});
if (check.spam.action === "block") {
// Hide the message.
}Python
pip install spamgoneIt needs Python 3.9 or later.
from spamgone import Spamgone
spamgone = Spamgone() # reads SPAMGONE_API_KEY
check = spamgone.checks.create(
"Turn $250 into $5,000 in 7 days. DM me on Telegram",
context={"content_type": "message", "author": {"id": "user_8412"}},
)
if check["spam"]["action"] == "block":
... # Hide the message.What they do for you
| Behavior | Node.js | Python |
|---|---|---|
| Timeout per attempt | timeoutMs, 3000 |
timeout, 3.0 seconds |
Retries on 429, 5xx and network errors |
maxRetries, 2 |
max_retries, 2 |
| Idempotency key on every POST, reused on retries | { idempotencyKey } to set your own |
idempotency_key= to set your own |
| When Spamgone can't be reached | failMode: "open" (default) or "closed" |
fail_mode="open" (default) or "closed" |
| Hook for degraded checks | onDegraded(error) |
on_degraded(error) |
| Errors | SpamgoneError with name, status, requestId |
SpamgoneError with name, status, request_id |
Retries wait at least as long as retry-after says. A wait over 10 seconds, such as a quota that resets tomorrow, fails at once instead of holding your request open.
Failing open
checks.create and checks.batch fail open by default. When Spamgone can't be reached, times out, or keeps answering with a server error after the retries, they return:
allowas the actiondegraded: true- no check ID
They also call your onDegraded (Node) or on_degraded (Python) hook. An outage never stops your users this way. Client errors, such as a wrong key, an invalid request or a used-up quota, still raise, because they need a fix on your side.
Set the fail mode to closed to raise instead. Every other method always raises.
Verify webhooks
Both libraries check the spamgone-signature header against the raw body, in constant time. They refuse deliveries signed more than 5 minutes ago.
import { verifyWebhook } from "spamgone";
const event = verifyWebhook({
payload: await request.text(),
signature: request.headers.get("spamgone-signature"),
secret: process.env.SPAMGONE_WEBHOOK_SECRET,
});from spamgone import verify_webhook
event = verify_webhook(
request.body,
request.headers.get("spamgone-signature"),
os.environ["SPAMGONE_WEBHOOK_SECRET"],
)Pass the body exactly as it arrived, before any JSON parsing. See Webhooks for the events.
Every endpoint
Both libraries cover the whole API with the same resources: checks, API keys, rules, settings, usage and webhooks. Node uses camelCase (spamgone.apiKeys.rotate) and Python snake_case (spamgone.api_keys.rotate). The Checks reference and API keys pages describe each call.