π Introduction
BASE URLs
RapidAPI Marketplace: https://oopspam.p.rapidapi.com/v1
OOPSpam: https://api.oopspam.com/v1
Welcome to the OOPSpam API!
OOPSpam API is a privacy-first and highly accurate anti-spam filter.
It is usually used for:
- Contact forms
- Comment & Review systems
- Live & Private chats
- Email marketing
- and any platform where message and content exchanged
Submit messages to the API and it will produce Spam Score
with a detailed report. Using Score
you can adjust the sensitivity level (also known as spam threshold) of spam filtering to fit your use case.
Example request body and all possible response fields
{
"senderIP": "91.203.67.110",
"email": "[email protected]",
"content": "Dear Agent, We are a manufacturing company which specializes in supplying Aluminum Rod with Zinc Alloy Rod to customers worldwide, based in Japan, Asia. We have been unable to follow up payments effectively for transactions with debtor customers in your country due to our distant locations, thus our reason for requesting for your services representation.",
"checkForLength": true,
"urlFriendly": false,
"allowedLanguages" : ["en"],
"allowedCountries" : ["it","us"],
"blockedCountries" : ["it","us"]
}
{
"Score": 6,
"Details": {
"isIPBlocked": false,
"isEmailBlocked": true,
"isContentSpam": "spam",
"langMatch": true,
"countryMatch": false,
"numberOfSpamWords": 1,
"spamWords": [
"dear"
],
"isContentTooShort": false
}
}
You can test the API right on your browser with your data on OOPSpam Dashboard or the RapidAPI marketplace.
The API is organized around REST. All requests should be made over SSL. All request and response bodies, including errors, are encoded in JSON.
π©βπ« Developer Support
As Developers we understand that no API Reference can answer every question.
We have a Developer to Developer support system where if you are working with our API you can speak directly to a developer.
If you have a question about our API just start a conversation with us using the chat widget on this page or via [email protected].
π Authentication
The OOPSpam API uses API keys to identify and authorize calls. You can register for a new API key in two ways:
The account on RapidAPI and on our Dashboard are dissociated. Each of these registration methods has its own base URL and API-KEY. You must therefore adapt your scripts according to your subscription by adapting the URL and your API KEY.
OOPSpam API expects the API key to be included in all API requests to the server in a header that looks like the following:
- For OOPSpam Dashboard endpoint:
X-Api-Key: API_KEY
- For RapidAPI endpoint:
X-Rapidapi-Key: API_KEY
Check out Using the API via Dashboard and Using the API via RapidAPI for additional information.
Using the API via Dashboard
The base URL : https://api.oopspam.com/v1
If you decided to subscribe directly on our site, you have OOPSpam Dashboard at your disposal.
It allows you to:
- To follow your consumption in real time
- Manage your subscription and change it if necessary
- Test the endpoint without writing a line of code.
Using the API via RapidAPI
The base URL : https://oopspam.p.rapidapi.com/v1
If you decided to subscribe to the API via RapidAPI marketplace then all information related to your subscription are available on the RapidAPI developer dashboard.
The RapidAPI developer dashboard is where you can see all of your apps, locate API keys, view analytics, and manage billing settings.
To access the dashboard, simply login to RapidAPI and select 'My Apps' in the top-right menu. Alternatively, you can head directly to https://rapidapi.com/developer/dashboard.
In the main dashboard, you will see account-wide analytics and account information. To get more detailed information, you can select tabs on the left-hand side of the screen.
App Specific Analytics
Using the RapidAPI dashboard, you can also view analytics specific to each app in your account. To do so, switch over to the 'Analytics' tab of your application in the dashboard.
On the top of the page, you'll be able to see:
- A chart with all the calls being made to the API
- Logs with all the request data
In each graph, you can view the following metrics:
API Calls
: how many requests are being madeError rates
: how many requests are error someLatency
: how long (on average) requests take to execute
You can find your API KEY under 'Security' tab.
π¦ Rate Limiting
OOPSpam API uses sliding window algorithm for rate limiting.
Headers via OOPSpam endpoint
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
Headers via RapidAPI endpoint
x-ratelimit-requests-limit: 40
x-ratelimit-requests-remaining: 1
Depending on your subscription, limits are placed on the number of API requests you may make using your API key per 30-days..
All responses from the API contain information about remaining and total rate limit. The special X-RateLimit-
headers have the following meaning:
Header | Description |
---|---|
X-RateLimit-Limit x-ratelimit-requests-limit |
The number of requests per month for the plan you are currently subscribed |
X-RateLimit-Remaining x-ratelimit-requests-remaining |
The number of requests remaining before you reach the limit of requests your application is allowed to make |
x-ratelimit-requests-reset |
Time at which the request counter is reset. Available only to RapidAPI endpoint |
If you exceeds this threshold your application will be unable to make further requests until the rate limit resets.
π― Endpoints
Spam Detection
Example request
require 'uri'
require 'net/http'
require 'openssl'
# Make sure to use correct base URL
#url = URI("https://oopspam.p.rapidapi.com/v1/spamdetection")
url = URI("https://api.oopspam.com/v1/spamdetection")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
# Make sure to use correct HEADERS based on your endpoint
#request["x-rapidapi-key"] = 'YOUR_API_KEY'
#request["x-rapidapi-host"] = 'oopspam.p.rapidapi.com'
request["X-Api-Key"] = 'YOUR_API_KEY'
request.body = "{\n \"checkForLength\": true,\n \"content\": \"Dear Agent, We are a manufacturing company which specializes in supplying Aluminum Rod with Zinc Alloy Rod to customers worldwide, based in Japan, Asia. We have been unable to follow up payments effectively for transactions with debtor customers in your country due to our distant locations, thus our reason for requesting for your services representation.\",\n \"senderIP\": \"185.234.219.246\",\n \"email\": \"[email protected]\"\n}"
response = http.request(request)
puts response.read_body
import requests
# Make sure to use correct base URL
#url = "https://oopspam.p.rapidapi.com/v1/spamdetection"
url = "https://api.oopspam.com/v1/spamdetection"
payload = "{\n \"checkForLength\": true,\n \"content\": \"Dear Agent, We are a manufacturing company which specializes in supplying Aluminum Rod with Zinc Alloy Rod to customers worldwide, based in Japan, Asia. We have been unable to follow up payments effectively for transactions with debtor customers in your country due to our distant locations, thus our reason for requesting for your services representation.\",\n \"senderIP\": \"185.234.219.246\",\n \"email\": \"[email protected]\"\n}"
# Make sure to use correct HEADERS based on your endpoint
headers = {
'content-type': "application/json",
'X-Api-Key': "YOUR_API_KEY",
#'x-rapidapi-key': "YOUR_API_KEY",
#'x-rapidapi-host': "oopspam.p.rapidapi.com"
}
response = requests.request("POST", url, data=payload, headers=headers)
print(response.text)
curl --request POST \
# Make sure to use correct base URL
--url https://api.oopspam.com/v1/spamdetection \
# --url https://oopspam.p.rapidapi.com/v1/spamdetection \
--header 'content-type: application/json' \
# Make sure to use correct HEADERS based on your endpoint
--header 'X-Api-Key: YOUR_API_KEY'
# --header 'x-rapidapi-host: oopspam.p.rapidapi.com' \
# --header 'x-rapidapi-key: YOUR_API_KEY' \
--data '{
"checkForLength": true,
"content": "Dear Agent, We are a manufacturing company which specializes in supplying Aluminum Rod with Zinc Alloy Rod to customers worldwide, based in Japan, Asia. We have been unable to follow up payments effectively for transactions with debtor customers in your country due to our distant locations, thus our reason for requesting for your services representation.",
"senderIP": "185.234.219.246",
"email": "[email protected]",
"allowedCountries": [
"it",
"us"
],
"allowedLanguages": [
"en"
],
"blockedCountries": [
"ru"
],
}'
const data = JSON.stringify({
"checkForLength": true,
"content": "Dear Agent, We are a manufacturing company which specializes in supplying Aluminum Rod with Zinc Alloy Rod to customers worldwide, based in Japan, Asia. We have been unable to follow up payments effectively for transactions with debtor customers in your country due to our distant locations, thus our reason for requesting for your services representation.",
"senderIP": "185.234.219.246",
"email": "[email protected]",
"allowedCountries": [
"it",
"us"
],
"allowedLanguages": [
"en"
],
"blockedCountries": [
"ru"
]
});
const xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
// Make sure to use correct base URL
//xhr.open("POST", "https://oopspam.p.rapidapi.com/v1/spamdetection");
xhr.open("POST", "https://api.oopspam.com/v1/spamdetection");
xhr.setRequestHeader("content-type", "application/json");
// Make sure to use correct HEADERS based on your endpoint
xhr.setRequestHeader("X-Api-Key", "YOUR_API_KEY");
// xhr.setRequestHeader("x-rapidapi-key", "YOUR_API_KEY");
// xhr.setRequestHeader("x-rapidapi-host", "oopspam.p.rapidapi.com");
xhr.send(data);
HttpRequest request = HttpRequest.newBuilder()
// Make sure to use correct base URL
// .uri(URI.create("https://oopspam.p.rapidapi.com/v1/spamdetection"))
.uri(URI.create("https://api.oopspam.com/v1/spamdetection"))
.header("content-type", "application/json")
// Make sure to use correct HEADERS based on your endpoint
.header("X-Api-Key", "YOUR_API_KEY")
// .header("x-rapidapi-key", "YOUR_API_KEY")
// .header("x-rapidapi-host", "oopspam.p.rapidapi.com")
.method("POST", HttpRequest.BodyPublishers.ofString("{\n \"checkForLength\": true,\n \"content\": \"Dear Agent, We are a manufacturing company which specializes in supplying Aluminum Rod with Zinc Alloy Rod to customers worldwide, based in Japan, Asia. We have been unable to follow up payments effectively for transactions with debtor customers in your country due to our distant locations, thus our reason for requesting for your services representation.\",\n \"senderIP\": \"185.234.219.246\",\n \"email\": \"[email protected]\"\n}"))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
// Make sure to use correct base URL
var client = new RestClient("https://api.oopspam.com/v1/spamdetection");
// var client = new RestClient("https://oopspam.p.rapidapi.com/v1/spamdetection");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
// Make sure to use correct HEADERS based on your endpoint
request.AddHeader("X-Api-Key", "YOUR_API_KEY");
// request.AddHeader("x-rapidapi-key", "YOUR_API_KEY");
// request.AddHeader("x-rapidapi-host", "oopspam.p.rapidapi.com");
request.AddParameter("application/json", "{\n \"checkForLength\": true,\n \"content\": \"Dear Agent, We are a manufacturing company which specializes in supplying Aluminum Rod with Zinc Alloy Rod to customers worldwide, based in Japan, Asia. We have been unable to follow up payments effectively for transactions with debtor customers in your country due to our distant locations, thus our reason for requesting for your services representation.\",\n \"senderIP\": \"185.234.219.246\",\n \"email\": \"[email protected]\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
// Make sure to use correct base URL
url := "https://api.oopspam.com/v1/spamdetection"
// url := "https://oopspam.p.rapidapi.com/v1/spamdetection"
payload := strings.NewReader("{\n \"checkForLength\": true,\n \"content\": \"Dear Agent, We are a manufacturing company which specializes in supplying Aluminum Rod with Zinc Alloy Rod to customers worldwide, based in Japan, Asia. We have been unable to follow up payments effectively for transactions with debtor customers in your country due to our distant locations, thus our reason for requesting for your services representation.\",\n \"senderIP\": \"185.234.219.246\",\n \"email\": \"[email protected]\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("content-type", "application/json")
// Make sure to use correct HEADERS based on your endpoint
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
// req.Header.Add("x-rapidapi-key", "YOUR_API_KEY")
// req.Header.Add("x-rapidapi-host", "oopspam.p.rapidapi.com")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
<?php
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{
"checkForLength": true,
"content": "Dear Agent, We are a manufacturing company which specializes in supplying Aluminum Rod with Zinc Alloy Rod to customers worldwide, based in Japan, Asia. We have been unable to follow up payments effectively for transactions with debtor customers in your country due to our distant locations, thus our reason for requesting for your services representation.",
"senderIP": "185.234.219.246",
"email": "[email protected]",
}');
// Make sure to use correct base URL
$request->setRequestUrl('https://api.oopspam.com/v1/spamdetection');
// $request->setRequestUrl('https://oopspam.p.rapidapi.com/v1/spamdetection');
$request->setRequestMethod('POST');
$request->setBody($body);
// Make sure to use correct HEADERS based on your endpoint
$request->setHeaders([
'content-type' => 'application/json',
'X-Api-Key' => 'YOUR_API_KEY'
]);
// $request->setHeaders([
// 'content-type' => 'application/json',
// 'x-rapidapi-key' => 'YOUR_API_KEY',
// 'x-rapidapi-host' => 'oopspam.p.rapidapi.com'
// ]);
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
The above command may return JSON structured like this:
{
"Score": 6,
"Details": {
"isIPBlocked": true,
"isEmailBlocked": true,
"isContentSpam": "spam",
"langMatch": true,
"countryMatch": false,
"numberOfSpamWords": 1,
"spamWords": [
"dear"
],
"isContentTooShort": false
}
}
Note that OOPSpam API tries to return the result as soon as one of the analyses detects spam. Hence some fields may not appear in the response body. Say
senderIP
is blocked then it will return following response without doing other analyses:
{
"Score": 6,
"Details": {
"isIPBlocked": true,
"isContentTooShort": false
}
}
The endpoint analyses given parameters and returns overall spam score (Score
) including detailed detection results in structured JSON.
HTTP Request
POST /spamdetection
Request Body Parameters
Field | Definition |
---|---|
content |
string (required) Is a content/message you would like to be analyzed. |
senderIP |
string (optional) Is the IP address of the original content/message sender. This field value will be looked up in multiple IP denylists that previously detected sending spam. Although senderIP is an optional field, we recommend sending it.
Important:
|
email |
string (optional) Is the email address of the original content/message sender. This field value will be looked up in multiple email denylists that previously detected sending spam. Although email is an optional field, we recommend sending it.
Important:
|
checkForLength default:true |
boolean (optional) If the content is shorter than 20 characters, it will be considered spam (Score: 5 ) and returns isContentTooShort: true . |
urlFriendly default:falsebeta |
boolean (optional) Make the content parameter more link-friendly and reduce the impact of links on the spam score. |
allowedLanguages |
array (optional) This allows blocking content based on a content language. Let us know in what language(s) you expect the content to be by passing two-letter language(s) code to the parameter as an array. |
allowedCountries |
array (optional) Allow content only from a certain country or countries. All you need to do is pass the two-letter country code as an array.
Important: senderIP is required for this to work. |
blockedCountries |
array (optional) Block content from a certain country or countries. All you need to do is pass the two-letter country code as an array.
Important: senderIP is required for this to work. |
Response Body Parameters
Field | Definition |
---|---|
Score |
number - A value between 0-6 representing an overall spam score based on passed parameters. The higher this value, the more likely to be spam. |
Details |
A dictionary containing the result of different analyses. |
isIPBlocked |
boolean - Represents whether the value of parameter senderIP is blocked. |
isEmailBlocked |
boolean - Represents whether the value of parameter email is blocked. |
langMatch |
boolean - Represents whether the value of parameter allowedLanguages matches with the detected language by Language Detection algorithm. |
isContentSpam |
string - Represents the result of a Machine Learning algorithm on whether the content is a spam or nospam. |
numberOfSpamWords |
number - A value representing a number of spam words within the content. |
spamWords |
array - A value representing the top 10 spam words in a content |
isContentTooShort |
boolean - Represents whether the value of parameter content is too short (max. 20 characters) to be considered a meaningful sentence. Any content that is too short will be considered spam. |
countryMatch |
boolean - Represents whether an IP address (the value of senderIP ) originates from one of the countries you passed through allowedCountries and blockedCountries parameters. In case of a mismatch, the API returns the maximum spam Score of 6. |
See support language codes for allowedLanguages
field
Language | ISO 639-1 code | Language | ISO 639-1 code |
---|---|---|---|
Afrikaans | af | Japanese | ja |
Albanian | sq | Korean | ko |
Arabic | ar | Latin | la |
Basque | eu | Latvian | lv |
Belarusian | be | Lithuanian | lt |
Bengali | bn | Malay | ms |
Bokmal | nb | Norwegian | no |
Bulgarian | bg | Nynorsk | nn |
Catalan | ca | Persian | fa |
Chinese | zh | Polish | pl |
Croatian | hr | Portuguese | pt |
Czech | cs | Punjabi | pa |
Danish | da | Romanian | ro |
Dutch | nl | Russian | ru |
English | en | Slovak | sk |
Estonian | et | Slovene | sl |
Finnish | fi | Somali | so |
French | fr | Spanish | es |
German | de | Swedish | sv |
Greek | el | Tagalog | tl |
Gujarati | gu | Tamil | ta |
Hebrew | he | Telugu | te |
Hindi | hi | Thai | th |
Hungarian | hu | Turkish | tr |
Icelandic | is | Urdu | ur |
Indonesian | id | Vietnamese | vi |
Irish | ga | Welsh | cy |
Italian | it |
Report
You can use this endpoint to report any false positives and false negatives to us. All the submissions will be available on OOPSpam Dashboard under the Reported page. The status of each report will be either Solved or Pending. We then analyze them and improve detection for your use case. Every processed submission will be marked as Solved.
HTTP Request
Example request and response body
{
"senderIP": "91.203.67.110",
"email": "[email protected]",
"content": "Dear Agent, We are a manufacturing company which specializes in supplying Aluminum Rod with Zinc Alloy Rod to customers worldwide, based in Japan, Asia. We have been unable to follow up payments effectively for transactions with debtor customers in your country due to our distant locations, thus our reason for requesting for your services representation.",
"checkForLength": true,
"allowedLanguages" : ["en"],
"allowedCountries" : ["it","us"],
"blockedCountries" : ["ru"],
"shouldBeSpam": true
}
{
"message": "success"
}
POST /spamdetection/report
The request body is identical to /spamdetection endpoint. The only difference is an extra boolean field shouldBeSpam
which takes the value of true
or false
. This field tells us if a content is false negative or false positive.
Field | Definition |
---|---|
shouldBeSpam |
boolean (required) A value represents whether the reported misdetection should be spam or ham. Pass true for spam, false for ham. |
Here is an example listing on the dashboard:
π§ͺ Testing
After integrating the API, you may want to test various use cases. To help you get started, here's a table displaying the blocked IP addresses, email addresses, and content.
content | IP | |
---|---|---|
Good day, \r\n\r\nMy name is Eric and unlike a lot of emails you might get, I wanted to instead provide you with a word of encouragement β Congratulations\r\n\r\nWhat for? \r\n\r\nPart of my job is to check out websites and the work youβve done with pos-cash.de definitely stands out. \r\n\r\nItβs clear you took building a website seriously and made a real investment of time and resources into making it top quality.\r\n\r\nThere is, however, a catchβ¦ more accurately, a questionβ¦\r\n\r\nSo when someone like me happens to find your site β maybe at the top of the search results (nice job BTW) or just through a random link, how do you know? \r\n\r\n | 45.152.198.112, 196.16.74.95 | [email protected], [email protected] |
π‘ Tips
- Responded
Score
parameter value ranges from 0 to 6. A value 3 or higher can be considered spam. - Make async HTTP request instead of sync as the system check
senderIP
against multiple IP denylists until it finds it.
π¨ Errors
The OOPSpam API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Your API key is wrong. |
404 | Not Found -- The resource requested could not be found. |
406 | Not Acceptable -- You requested a format that isn't json. |
429 | Too Many Requests -- The API key making the request has exceeded our rate limits. |
500 | Internal Server Error -- We had a problem with our server. Try again later. |