Using the Spam Shield API

At its heart, Spam Shield is a database you can access via a REST API. You can use the Spam Shield API in your own projects by making simple HTTP calls to the REST API. We’re going to use Bash & HTTPie in these examples, but you could just as easily Curl, Python or whatever you want. We’re also going to use jq to parse the JSON response data.

To install the prerequisites on Ubuntu/Mint/Debian, you can do the following:

#
# Install HTTPie and JQ on Debian/Ubuntu systems
#
sudo apt install httpie jq

Simple API requests

This simple script populates the X-ApiKey header with the API Key and GETs the /account endpoint using “HTTPie”. The results are rinsed through “jq” to format the JSON nicely.

InformationResponses from Spam Shield will always contain a property called queryTime. If it doesn’t exist as a top-level property of the response object, you can assume the response is invalid.

#!/bin/bash

#
# Tested on Debian 11.
# Should work on any recent flavour of Debian, Ubuntu and other GNU/Linux distros.
#

# Replace this with your API key
SPAM_SHIELD_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx


#
# Example One: Display your account status
#
echo "Raw Account Status"
echo "=================="
http https://api.spamshield.cloud/account X-ApiKey:${SPAM_SHIELD_API_KEY} | jq .



# Blank line
echo

#
# Example Two: Get the account summary and store it in ACCOUNT_SUMMARY
#
ACCOUNT_SUMMARY="$(http https://api.spamshield.cloud/account X-ApiKey:${SPAM_SHIELD_API_KEY} | jq .)"
if [ $? -ne 0 ]; then
    echo "Failed to get Spam Shield account status"
else
    echo "Parsed Account Status"
    echo "====================="
    echo "Quota: $(echo "${ACCOUNT_SUMMARY}" | jq -r .dailyQuota)"
    echo "Spam Today: $(echo "${ACCOUNT_SUMMARY}" | jq -r .spamToday)"
    echo "Ham Today: $(echo "${ACCOUNT_SUMMARY}" | jq -r .hamToday)"
fi

API Key with restricted domains/sites

If you’ve restricted which sites can use your API key (recommended for agencies), you need to pass the calling hostname in the X-Caller HTTP header.

#
# Example Three: Using an API key with restricted domains
#
# Replace this with your API key
SPAM_SHIELD_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Automatically use the server's host name...
CALLER_HOST="$(hostname -f)"

# ...or set the caller host manually
CALLER_HOST=my-website.com

http https://api.spamshield.cloud/account \
	X-Caller:${CALLER_HOST} \
	X-ApiKey:${SPAM_SHIELD_API_KEY} | jq .