API Method "spam_check"

 

In order to use SPAM_CHECK method you have to buy a separate licence — Database API. Our prices are here: https://cleantalk.org/price#api

You can purchase it here on your billing page: https://cleantalk.org/my/bill/api

 

Method's response is information about existence of IP and e-mail records in our database for a long period of time.

It may differ from results of blacklist checking on our public page — https://cleantalk.org/blacklists — the website shows current spam status only.

 

What's the difference in data that methods SPAM_CHECK and CHECK_NEWUSER (or CHECK_MESSAGE) return?

They check spam activity for different time periods and serve different purposes as well:

 • SPAM_CHECK takes last 6 months of spam history and responses accordingly. It is also needed to know if an e-mail exists or not.

 • CHECK_NEWUSER (or CHECK_MESSAGE) takes current status of a record, i.e. last 2 weeks of spam history, and is needed to check any IP or e-mail on the fly. Many tests are being performed for a record (relevance to website text, language, nickname, JavaScript tests and etc.) to define whether it is spam right now or not.

 

Call Requires GET Parameters:

 

Optional GET Parameters:

  • ip — IP address to check
  • email — e-mail address to check (The result is given for the last 6 months)
  • date — date to check in YYYY-MM-DD format (It can be applied only to IP addresses)

 

Example request with IP:

https://api.cleantalk.org/?method_name=spam_check&auth_key=123456&email=stop_email@example.com&ip=127.0.0.1

 

Example request with date:

https://api.cleantalk.org/?method_name=spam_check&auth_key=123456&email=stop_email@example.com&ip=127.0.0.1&date=2017-01-31

 

API returns JSON string, for example:

{"data":{"127.0.0.1":{"appears":0},"stop_email@example.com":{"appears":1,"frequency":"999","spam_rate":"100","updated":"2019-04-24 23:33:00","frequency_time_10m":"1","frequency_time_1h":"10","frequency_time_24h":"1000"}}}

 

Response Explanation:

  • data — array with checked records,
  • appears — marker that defines the record status in the blacklists 0|1,
  • spam_rate — a rating of spam activity from 0 to 100%. 100% means certain spam,
  • frequency — is a number of websites that reported about spam activity of the record. It can be from 0 up to 9999,
  • frequency_time_10m — 10 minute activity,
  • frequency_time_1h — 1 hour activity,
  • frequency_time_24h — 24 hour activity.

In case of 'date' parameter response contains results on given date only.

 

Multiple Records Check:

You can submit multiple records to test per 1 call, to do that use POST options:

  • data — string with records to check separated by ','.

 

Example:

wget -O- --post-data='data=stop_email@example.com,10.0.0.1,10.0.0.2' https://api.cleantalk.org/?method_name=spam_check\&auth_key=123456

 

Response:

{"data":{"stop_email@example.com":{"appears":1,"frequency":"999","updated":"2019-04-24 23:33:00"},"10.0.0.1":{"appears":0},"10.0.0.2":{"appears":0}}}

 

Restrictions:

If you get calls limit, API returns error notice. Example:

{"error_message":"Calls limit exceeded.","error_no":10}

Current calls limit is 100 per 60 seconds.

 

If you get data elements limit in spam_check method, API returns error notice. Example:

{"error_message":"Recevied 1001 records to check, maximum 1000 records check perl call.","error_no":8}

Current data elements limit is 1000.

 

Recommended timeout is no more than 180 seconds.

 

Notice: if date is sent in the request, then the request may be implemented a little longer.

 

 

Description of Several Examples of API Responses

 

Below you will find several examples and descriptions of the parameters for possible server response options, such as:

  • "appears" — marker that defines the record status in the blacklists 0|1;
  • "spam_rate" — a rating of spam activity from 0 to 100%. 100 means certain spam;
  • "frequency" — is a number of web-sites that reported about spam activity of the record. It can be from 0 up to 9999;
  • "frequency_time_10m" — 10 minutes activity;
  • "frequency_time_1h" — 1 hour activity;
  • "frequency_time_24h" — 24 hours activity.

 

Example:

"ip":{"appears":1}

Exlanation:

  • "appears":1 — IP is in blacklists;

 

Example:

"ip":{"appears":0}

Exlanation:

  • "appears":0 — IP is not in blacklists;

 

Example:

"ip":{"appears":0, "frequency":"15"}

Exlanation:

  • "appears":"0" — IP is not in blacklists;
  • "frequency":"15" — 15 websites reported about spam activity of this IP.

 

Example:

"ip":{ "appears":"0","spam_rate":"1","frequency":"1","frequency_time_10m":"1","frequency_time_1h":"1","frequency_time_24h":"1"}

Explanation:

  • "appears":0 — IP is not in blacklist;
  • "spam_rate":"1" — there was 1 request and it was detected as spam;
  • "frequency":"1" — 1 web-site reported about spam activity of this IP;
  • "frequency_time_10m":"1" — there was 1 spam request time in 10 minutes;
  • "frequency_time_1h":"1" — there was 1 spam request in 1 hour;
  • "frequency_time_24h":"1" — there was 1 spam request in 24 hours.

 

Example: 

"email":{ "appears":0,"spam_rate":"1","frequency":"1","frequency_time_10m":"1","frequency_time_1h":"1","frequency_time_24h":"1","exists":"1"}

Explanation:

  • "appears":"0" — email is not in blacklist;
  • "spam_rate":"1" — there was 1 request and it was detected as spam;
  • "frequency":"1" — 1 web-site reported about spam activity of this email;
  • "frequency_time_10m":"1" — there was 1 spam request time in 10 minutes;
  • "frequency_time_1h":"1" — there was 1 spam request in 1 hour;
  • "frequency_time_24h":"1" — there was 1 spam request in 24 hours.
  • "exists":"1" — the real email that exists on a mail server.

 

 

Method SPAM_CHECK should be used exclusively for mass checking of IPs and e-mails for spam activity. For other purposes you could use other methods:

  • check_message (requires Standard Anti-Spam Licence) — API spam filter to check posts and comments.
  • check_newuser (requires Standard Anti-Spam Licence) — Registration check.
  • send_feedback (requires Standard Anti-Spam Licence) — Send feedback to CleanTalk.
  • backlinks_check (requires Database API Licence) — Mass check for backlinks in spam comments.

 

 


Perhaps it would also be interesting