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:


Example request with date:


API returns JSON string, for example:

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


Response explanation:

  • data - array with checked records,
  • record - array with details per record,
  • 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.

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 ','.


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



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



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.