NAV
cURL ruby python php javascript java csharp go

👋 Introduction

BASE URLs

RapidAPI Marketplace: https://oopspam.p.rapidapi.com

OOPSpam: https://api.oopspam.com/

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 systems
  3. Live chats
  4. and any platform where contents exchaged

You submit messages to us via the API and it produces Spam Score with a detailed report. Using Score you can adjust the sensitivity level of spam filter to your use case.

Example request and all possible response fields

{
    "senderIP": "91.203.67.110",
    "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"]
}
{
  "Score": 6,
  "Details": {
    "isIPBlocked": false,
    "isContentSpam": "spam",
    "langMatch": true,
    "countryMatch": false,
    "numberOfSpamWords": 0,
    "isContentTooShort": false
  }
}

OOPSpam API request and response example

You can test the API right on your browser with your data on OOPSpam Dashboard or the RapidAPI marketplace.

Run in Postman

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 contact@oopspam.com.

🔑 Authentication

The OOPSpam API uses API keys to identify and authorise calls. You can register for a new API key in two ways:

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

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:

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/

If you decided to subscribe directly on our site, you have OOPSpam Dashboard at your disposal.

It allows you to:

OOPSpam Dashboard OOPSpam Dashboard OOPSpam Dashboard

Using the API via RapidAPI

The base URL : https://oopspam.p.rapidapi.com/

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:

In each graph, you can view the following metrics:

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

RapidAPI Developer Dashboard

đŸšĻ Rate Limiting

Headers via RapidAPI endpoint

x-ratelimit-requests-limit: 40
x-ratelimit-requests-remaining: 1

Headers via OOPSpam endpoint

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998

Depending on your subscription, limits are placed on the number of API requests you may make using your API key. All responses from the API contain information about the current state of rate-limiting. 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}"

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}"

# 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",
    "allowedCountries": [
        "it",
        "us"
    ],
    "allowedLanguages": [
        "en"
    ]
}'
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",
  "allowedCountries": [
        "it",
        "us"
    ],
    "allowedLanguages": [
        "en"
    ]
});

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}"))
        .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}", 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}")

    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"
}');

// 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,
    "isContentSpam": "spam",
    "langMatch": true,
    "countryMatch": false,
    "numberOfSpamWords": 0,
    "isContentTooShort": false
  }
}

Note that OOPSpam API tries to return the result as soon as one of the analyses detects spam. Hence some field 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 /v1/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 blocklisted IPs lists 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 regarding content to you, not your IP.
  • IP addresses 127.0.0.1, 1.1.1.1, ::1 including private IPs are by default blocked.
checkForLength default:true boolean (optional) If the content is shorter than 20 characters, it will be considered spam (Score: 5) and returns isContentTooShort: true.
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.

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 blocklisted.
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.
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 parameter. 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

🔌 Integration

You can integrate OOPSpam API with any platform where content is exchanged. While we try to integrate it into the different platforms, our main focus is to put more work on development, improvements, and documentation/tutorials. If you integrate OOPSpam into your platform, let us know. We'd be happy to publish it here.

WordPress

OOPSpam has a WordPress plugin that integrates with the API. It filters both comments and contact form submissions.

Supported Contact Form solutions

As the plugin works with OOPSpam API, it supports all spam protection capabilities out of the box.

The plugin currently supports the following settings:

"OOPSpam WordPress plugin screenshot"

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