OOPSpam Anti-Spam API documentation

This documentation is almost identical to what we have on RapidAPI.

API Reference

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

If you are using OOPSpam through RapidAPI, make sure to include x-rapidapi-key as a request header with your API key as a value. You can get an API key by subscribing to one of the plans.

Check out our RapidAPI page for example requests in different programming languages.

Also make sure check out Tips section.

Important Flag a content spam solely based on Score (aka Spam Score). We recommend assuming Spam Score 3 or higher to be spam.


/v1/spamdetection (POST)

Overview

The /v1/spamdetection endpoint analyses given parameters and returns overall spam score including detailed detection results in structured JSON.

Request
{
   "senderIP": "38.125.233.253",
   "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.",
   "contentLang" : ["en"]             
}
Fields
  • senderIP : is the IP of the original content 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. Don't send 127.0.0.1, it is by default blocked.

    Important: This field should include spammer's IP, in other words, whoever submitted regarding content to you, not your IP.

  • content : is a content you would like to be analyzed.

  • contentLang : (optional) In what language(s) you expect the content to be?
    Pass two-letter language(s) code to the parameter as an array. Check out an example request & support languages.
  • checkForLength : (optional) Is a boolean value. Whenever you send content to the API, it checks if it is more than 20 characters long. In case the content is shorter than 20 characters than it is considered as spam (Spam Score: 5) and returns isContentTooShort: true.
    Use checkForLength: false to disable this feature. This is recommended only for live chat systems or where you fill like no need for a length check.

Note on contentLang: If you know that you may receive content in a few languages (or single language), say English, Vietnamese, Turkish then your contentLang parameter should have JSON array with multi-languages ["en","vi", "tr"]:

{
   "senderIP": "38.125.233.253",
   "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.",
   "contentLang" : ["en","vi", "tr"]             
}

Following languages are supported:

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-cn 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
Response
{
    "Score": 6,
    "Details": {
        "isIPBlocked": true,
        "langMatch": true,
        "isContentSpam": "spam",
        "numberOfSpamWords": 1,
        "isContentTooShort": true,
        "isContentAdult": true
    }
}
Fields

In case of successful request, following structured JSON will be responded:

  • Score: An number between 0-6 representing an overall spam score based on passed parameters. The higher this value, the more likely to be spam. A value 3 or higher can be considered spam.
  • Details: A dictionary containing the result of different analyses.
    • isIPBlocked : A boolean value representing whether the value of parameter senderIP IP is blocklisted.
    • langMatch : A boolean value representing whether the value of parameter contentLang matches with the detected language by Language Detection algorithm.
    • isContentSpam : A string containing the result of a Machine Learning algorithm on whether the content is a spam or notspam.
    • numberOfSpamWords : A number representing a number of spam words within the content.
    • isContentTooShort: A boolean value representing whether the value of content is too short to consider a meaningful sentence. Any content that is too short will be considered as spam.
    • isContentAdult: A boolean value representing whether the value of content is an adult content. Any content that is detected as adult content will be considered as spam. The maximum spam score 6 will be returned.

Error handling

A successful request will return HTTP status code 200. In case you didn't include necessary headers in your requests such as an API key which you will get status code 401 (Unauthorized) with an explanatory message as the part of response's body. Other possible errors can be :

  • An invalid JSON format
  • Generic error message

With all (error) cases, you will get a JSON object with an error code and message which looks like this:

{
   "code":"5740538",
   "message":"Invalid JSON format. Please verify and resubmit."
}

Limitations

  • To check against blocklisted IPs ( senderIP) only IPv4 is supported. IPv6 will be ignored.

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 blocklisted IPs lists until it finds it. The latency is low tho (currently 565ms).
  • Don't send 127.0.0.1, ::1, 1.1.1.1 as a value of senderIP, they are by default blocked.

Whatever question you have please contact us via contact@oopspam.com or through Twitter. I'd be happy to help!