Docs pages

Response

Every message that gets an answer returns the same four fields, with HTTP status 200.

Fields

Response fields
Field	Type	Description
`detection_id`	string, UUID	A unique id for this answer. It is shown in your logs. A repeated request returns the first id.
`status`	string	"checked" when the message got a verdict, or "skipped" when there was nothing in it to check.
`spam_probability`	number, 0–1	How likely the message is spam. A higher number means more likely. Always 0 when skipped.
`is_spam`	boolean	The verdict. Always false when skipped.

Checked

The message got a verdict. Spam probabilities run from 0 to 1 and show in your logs like 0.97.

200 OK

{
  "detection_id": "6f1c2a9e-5b8d-4c1e-9a7b-3d2e1f0a9b8c",
  "status": "checked",
  "spam_probability": 0.97,
  "is_spam": true
}

Skipped

Nothing in the message could be checked, for example every field was empty or of a type we ignore. It does not count towards your plan. Treat it as no result.

200 OK

{
  "detection_id": "9a4e8f20-7c13-4b6d-a5e1-2d8c0f9b3e71",
  "status": "skipped",
  "spam_probability": 0,
  "is_spam": false
}

Repeated requests

Sending the same Idempotency-Key with the same body again returns the first answer with the header Idempotency-Replayed: true. It does not count again.

The same Idempotency-Key with a different body gets 409 idempotency_conflict. Use a new key for each message.

Use the answer

Mark the message as spam only when status is "checked" and is_spam is true.
Let every other message through: clean, skipped, any error, or no answer in time.