. NAV
cURL ruby python php javascript java csharp go

πŸ‘‹ 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:

  1. Contact forms
  2. Comment & Review systems
  3. Live & Private chats
  4. Email marketing
  5. Sign up protection (from fake accounts)
  6. E-commerce card-testing attack & chargeback protection
  7. 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
  }
}

OOPSpam API request and response example

You can test the API directly in your browser with your data on the OOPSpam Dashboard or the RapidAPI Marketplace.

Run in Postman

Run in Insomnia

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:

  1. Recommended Directly on our dashboard
  2. OOPSpam on RapidAPI marketplace

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:

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

OOPSpam Dashboard OOPSpam Dashboard

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

In each graph, you can view the following metrics:

You can find your API KEY under 'Security' tab.

RapidAPI Developer Dashboard

🚦 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 '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\": \"testing@example.com\"\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\": \"testing@example.com\"\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,
    "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 data = JSON.stringify({
    "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 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\": \"testing@example.com\"\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\": \"testing@example.com\"\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\": \"testing@example.com\"\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,
    "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",
}');

// 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.

Run in Postman

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:

  • This field should include spammer's IP, in other words, whoever submitted content to you, not your IP.
  • IP addresses 127.0.0.1, 1.1.1.1, ::1 including private IPs are by default blocked.
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:

  • This field should include spammer's email, in other words, whoever submitted content to you, not your email.
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:

OOPSpam Dashboard Reported page

πŸ§ͺ 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 Email
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

🚨 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.