π Introduction
BASE URLs
OOPSpam: https://api.oopspam.com/v1
RapidAPI Marketplace: https://oopspam.p.rapidapi.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
- Sign up protection (from fake accounts)
- E-commerce card-testing attack & chargeback protection
- and any platform where messages and content are exchanged
Submit messages to the API and it will generate a spam Score
with a detailed report. Using the Score
you can adjust the sensitivity level (also known as spam threshold) of spam filtering to suit your use case. Our recommendation is to consider Score:3 and higher as spam, and anything lower than that should be considered ham (not spam).
Example request body and all possible response fields
{
"senderIP": "91.203.67.110",
"email": "testing@example.com",
"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.",
"blockTempEmail": false,
"logIt": false,
"checkForLength": true,
"urlFriendly": false,
"allowedLanguages" : ["en"],
"allowedCountries" : ["it","us"],
"blockedCountries" : ["ru","cn"]
}
{
"Score": 6,
"Details": {
"isIPBlocked": false,
"isEmailBlocked": true,
"isContentSpam": "spam",
"langMatch": true,
"countryMatch": false,
"numberOfSpamWords": 1,
"spamWords": [
"dear"
],
"isContentTooShort": false
}
}
You can test the API directly in your browser with your data on the OOPSpam Dashboard or the RapidAPI Marketplace.
The API is built 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 contact@oopspam.com.
π 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.
The OOPSpam API expects the API key to be included in all API requests to the server in a header that looks like this:
- 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 have chosen to subscribe directly on our site, you will have the OOPSpam Dashboard at your disposal.
It allows you to
- Follow your usage in real time
- Manage your subscription and change it if necessary
- Test the endpoint without writing a single line of code.
- Access to the Domain Reputation Watch and the API
- Access to live chat support
Using the API via RapidAPI
The base URL : https://oopspam.p.rapidapi.com/v1
If you have chosen to subscribe to the API through the RapidAPI Marketplace, all information related to your subscription is available in the RapidAPI Developer Dashboard.
The RapidAPI Developer Dashboard allows you to view all your applications, locate API keys, view analytics, and manage billing settings.
To access the dashboard, simply login to RapidAPI and select 'My Apps' from the top right menu. Alternatively, you can go directly to https://rapidapi.com/developer/dashboard.
The main dashboard displays account-wide analytics and account information.
For more detailed information, you can select tabs on the left side of the screen.
App Specific Analytics
The RapidAPI Dashboard also allows you to view analytics specific to each application in your account. To do this, go to the Analytics tab for your application in the dashboard.
At the top of the page, you'll see
- A graph of all calls made to the API
- Logs with all request data
In each graph, you can view the following metrics:
API Calls
: how many requests are being madeError rates
: how many requests are errorLatency
: 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 to |
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 requests counter is reset. Available only for RapidAPI endpoint only |
If you exceed this limit, your application will not be able to make any more requests until the rate limit is reset.
π― Endpoints
Spam Detection
Example request
require 'uri'
require 'net/http'
require 'json'
API_KEY = 'YOUR_API_KEY'
API_URL = 'https://api.oopspam.com/v1/spamdetection'
def check_for_spam
uri = URI(API_URL)
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_PEER
request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request['X-Api-Key'] = API_KEY
request_body = {
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: "testing@example.com"
}
request.body = request_body.to_json
response = http.request(request)
if response.is_a?(Net::HTTPSuccess)
JSON.parse(response.body)
else
raise "Request failed with status: #{response.code}, body: #{response.body}"
end
end
begin
result = check_for_spam
puts result
rescue StandardError => e
puts "An error occurred: #{e.message}"
end
import requests
import json
API_KEY = 'YOUR_API_KEY'
API_URL = 'https://api.oopspam.com/v1/spamdetection'
def check_for_spam():
headers = {
'Content-Type': 'application/json',
'X-Api-Key': API_KEY
}
payload = {
'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': "testing@example.com"
}
try:
response = requests.post(API_URL, json=payload, headers=headers)
response.raise_for_status() # Raises an HTTPError for bad responses
return response.json()
except requests.exceptions.RequestException as e:
print(f"An error occurred: {e}")
return None
if __name__ == "__main__":
result = check_for_spam()
if result:
print(json.dumps(result, indent=2)) # Pretty print the JSON response
curl --request POST \
--url https://api.oopspam.com/v1/spamdetection \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: YOUR_API_KEY' \
--data '{
"checkForLength": true,
"blockTempEmail": false,
"logIt": false,
"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": "testing@example.com",
"allowedCountries": [
"it",
"us"
],
"allowedLanguages": [
"en"
],
"blockedCountries": [
"ru"
]
}'
const apiKey = 'YOUR_API_KEY';
const apiUrl = 'https://api.oopspam.com/v1/spamdetection';
const requestData = {
checkForLength: true,
blockTempEmail: false,
logIt: false,
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: "testing@example.com",
allowedCountries: ["it", "us"],
allowedLanguages: ["en"],
blockedCountries: ["ru"]
};
async function checkForSpam() {
try {
const response = await fetch(apiUrl, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Api-Key': apiKey
},
body: JSON.stringify(requestData)
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
console.log(data);
return data;
} catch (error) {
console.error('There was a problem with the fetch operation:', error);
}
}
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.oopspam.com/v1/spamdetection"))
.header("content-type", "application/json")
.header("X-Api-Key", "YOUR_API_KEY") // Replace with your actual API key
.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\": \"testing@example.com\"\n}"))
.build();
try {
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
} catch (Exception e) {
e.printStackTrace();
}
using RestSharp;
using Newtonsoft.Json; // or System.Text.Json
// Create a class to represent the request body
public class SpamRequest
{
[JsonProperty("checkForLength")]
public bool CheckForLength { get; set; }
[JsonProperty("content")]
public string Content { get; set; }
[JsonProperty("senderIP")]
public string SenderIP { get; set; }
[JsonProperty("email")]
public string Email { get; set; }
}
public class Program
{
public static void Main(string[] args)
{
// Create a client with the correct base URL
var client = new RestClient("https://api.oopspam.com/v1/spamdetection");
// Create a request
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("X-Api-Key", "YOUR_API_KEY"); // Use actual API key
// Create the request body object with exact property names
var spamRequest = new SpamRequest
{
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 = "testing@example.com"
};
// Serialize the object to JSON with the exact names
string requestBody = JsonConvert.SerializeObject(spamRequest);
// Add the JSON payload to the request body
request.AddParameter("application/json", requestBody, ParameterType.RequestBody);
// Execute the request
IRestResponse response = client.Execute(request);
System.Console.WriteLine(response.Content);
}
}
package main
import (
"fmt"
"io/ioutil"
"net/http"
"strings"
"log"
)
func main() {
// Make sure to use correct base URL
url := "https://api.oopspam.com/v1/spamdetection"
payload := strings.NewReader(`{
"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": "testing@example.com"
}`)
req, err := http.NewRequest("POST", url, payload)
if err != nil {
log.Fatalf("Error creating request: %v", err)
}
// Set the required headers
req.Header.Add("Content-Type", "application/json")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
client := &http.Client{}
res, err := client.Do(req)
if err != nil {
log.Fatalf("Error sending request: %v", err)
}
defer res.Body.Close()
body, err := ioutil.ReadAll(res.Body)
if err != nil {
log.Fatalf("Error reading response body: %v", err)
}
fmt.Println("Response Status:", res.Status)
fmt.Println("Response Body:", string(body))
}
<?php
const API_KEY = 'YOUR_API_KEY';
const API_URL = 'https://api.oopspam.com/v1/spamdetection';
function checkForSpam() {
$payload = json_encode([
'checkForLength' => true,
'blockTempEmail' => false,
'logIt' => false,
'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' => "testing@example.com",
]);
$ch = curl_init(API_URL);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-Api-Key: ' . API_KEY
]
]);
$response = curl_exec($ch);
if ($response === false) {
$error = curl_error($ch);
curl_close($ch);
throw new Exception("cURL Error: $error");
}
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode >= 400) {
throw new Exception("HTTP Error: $httpCode, Response: $response");
}
return json_decode($response, true);
}
try {
$result = checkForSpam();
echo json_encode($result, JSON_PRETTY_PRINT);
} catch (Exception $e) {
echo "An error occurred: " . $e->getMessage();
}
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:
|
blockTempEmail default:false |
boolean (optional) Block temporary/disposable emails. |
checkForLength default:true |
boolean (optional) If the content is shorter than 20 characters, it will be considered spam (Score: 5 ) and returns isContentTooShort: true . |
logIt default:false |
boolean (optional) Allows you to view logs in the OOPSpam Dashboard. |
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 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 that represents an overall spam score based on the parameters passed. The higher the score, the more likely it is to be spam. |
Details |
A dictionary containing the results of different analyses. |
isIPBlocked |
boolean - Represents whether the value of parameter senderIP is blocked. |
isEmailBlocked |
boolean - Represents whether the value of the parameter email is blocked. |
langMatch |
boolean - Represents whether the value of the 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 the parameter content is too short (20 characters or less) to be considered a meaningful sentence. Any content that is too short is 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 either be Solved or Pending. The system (or human intervention if necessary) will then analyze them and improve the 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": "testing@example.com",
"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.",
"blockTempEmail": false,
"logIt": false,
"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:
Domain Reputation
This endpoint evaluates the reputation of a given domain name by cross-referencing it against multiple authoritative sources, including Google, Microsoft, Mozilla, and various other reputable security providers.
Note: The list of providers may be updated periodically to ensure comprehensive coverage.
Example request
{
"domain": "example.com"
}
HTTP Request
POST /reputation/domain
Request Body Parameters
Field | Definition |
---|---|
domain |
string - The fully qualified domain name to be checked without `https`, `http`, `www`. |
An example response for a blocked domain
{
"Blocked": true,
"Blocker": [
"SURBL",
"Spamhaus"
]
}
An example response for a safe domain
{
"Blocked": false,
"Blocker": []
}
Response Body Parameters
Field | Definition |
---|---|
Blocked |
boolean - Indicates whether the specified `domain` parameter is flagged as blocked or unsafe by any of the reputation sources. |
Blocker |
array - Lists the names of specific providers that have flagged the domain, if any. |
π§ͺ Testing
After integrating the API, you may want to test different use cases. To help you get started, here's a table of 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 | testing@example.com, test@test.com |
π‘ Tips
- Responded
Score
parameter value ranges from 0 to 6. Any value of 3 or higher can be regarded as spam. - Make an async HTTP request instead of a sync one, as the system will check the sender IP against multiple IP denial lists 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. |