API Method spam_check

This method should be used only for mass check IPs, emails for spam activity. For other purposes you could use other methods:

Method result is an information about existing of IP/email records in our database for all time. It may differ from results of blacklist checking on our site - https://cleantalk.org/blacklists - which shows current spam status only.

Call required GET params:

Optional GET params:

  • ip - ip address to check
  • email - email 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 witch define 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.

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 the 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 description of the parameters for possible server response options, such as:

  • "appears" - marker wich define 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 blacklist;

 

Example:

"ip":{"appears":0}

Exlanation:

  • "appears":0 - IP is not in blacklist;

 

Example:

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

Exlanation:

  • "appears":"0" - IP is not in blacklist;
  • "frequency":"15" - 15 web-sites 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"}

Exlanation:

  • "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.