Use the API to check for spam

To check a message for spam, create a JSON document that represents the message body, message fields and the sender, like this:

{
	"ip": "123.123.123.123",
	"message": "I am not a real customer. I just want to take your money.",
	"fields": {
		"email-from": "nasty-bot@awful-domain.xyz",
		"author-url": "http://a-rotten-website.xyz/"
	}
}

Property	Notes
ip	The IPv4 or IPv6 address of the sender/browser/client.
message	The message body. You don’t need to sanitise this – as long as the JSON is valid, the request will be processed.
fields	A collection of user-defined key/value pairs for additional data. As long as the keys and values are valid JSON, you can put what you like in here, although it’s recommended you keep these simple, with things like email addresses and phone numbers.

Spam Shield API request to classify a message as junk or not-junk

To classify the message, POST the JSON document to the /spam/check endpoint with the X-ApiKey header set. To do this from the command-line using HTTPie, you could do something like this:

#!/bin/bash

# Replace this with your API key
SPAM_SHIELD_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

MESSAGE_BODY='I am not a real customer. I just want to take your money.'
SENDER_IP='123.123.123.123'
SENDER_EMAIL='nasty-bot@awful-domain.xyz'
SENDER_URL='http://a-rotten-website.xyz/'

REQUEST="{
	\"ip\": \"${SENDER_IP}\",
	\"message\": \"${MESSAGE_BODY}\",
	\"fields\": {
		\"email-from\": \"${SENDER_EMAIL}\",
		\"author-url\": \"${SENDER_URL}\"
	}
}"

# Uncomment this to display/check the request looks OK.
# echo "${REQUEST}" | jq .

#
# POST the message to Spam Shield and rinse the result
# through "jq" to present the JSON response nicely.
#
echo "${REQUEST}" | \
	http https://api.spamshield.cloud/spam/check X-ApiKey:${SPAM_SHIELD_API_KEY} | \
	jq .

This will return a comprehensive classification, as well as a top-level score, like this:

{
	"result": {
		"score": 5.9,
		"hamThreshold": -1.5,
		"spamThreshold": 2.9,
		"classification": "Spam",
		"isSpam": true
	},
	"classifiers": [
		{
			"name": "IP Reputation Checker",
			"score": 4
		},
		{
			"name": "Quick Sanity Checker",
			"score": 0
		},
		{
			"name": "Bad Word Scanner",
			"score": 0
		},
		{
			"name": "Bad Phrase Scanner",
			"score": 0
		},
		{
			"name": "URL Scanner",
			"score": -0.1
		},
		{
			"name": "Field Scanner",
			"score": 2
		}
	],
	"sender": {
		"ipAddress": "123.123.123.123",
		"countryCode2": "CN"
	},
	"errors": [],
	"messages": [
		"Found a Regex field match",
		"Bayes Scores :: Spam=0.01 :: Ham=0.03",
		"Sender IP address is a known spammer"
	],
	"queryTime": "2022-06-23 16:08:37.858"
}