Perspective API shuts down on December 31, 2026.Switch by changing one URL

SDKs

Official libraries for Node.js and Python. Both have no dependencies and are safe by default:

  • 3-second timeouts
  • retries that respect retry-after and 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 spamgone

It 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 spamgone

It 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:

  • allow as the action
  • degraded: 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.