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 .