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/spam-ip — 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 (IPv4 or IPv6 standard format)
  • 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)
  • email_<SHA256> - email SHA256 hash
  • ip4_<SHA256>- IPv4 address SHA256 hash
  • ip6_<SHA256>- IPv6 address SHA256 hash

 

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,"sha256":"12ca17b49af2289436f303e0166030a21e525d266e209267433801a8fd4071a0","network_type":null},"stop_email@example.com":{"appears":1,"sha256":"6d42ca0235d72b01a2b086ad53b5cfac24b5a444847fad70250e042d7ca8bf59","disposable_email":1,"frequency":"999","updated":"2019-04-24 23:33:00","spam_rate":"0","frequency_time_10m":0,"frequency_time_1h":0,"frequency_time_24h":0,"exists":null}}}

 

Response Explanation:

  • data — array with checked records,
  • appears — the marker that defines the record status in the blacklists 0|1,
  • sha256 - address sha256 hash
  • network_type - special net type (hosting)
  • 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.

 

gmail.com addresses features  

 

If gmail.com address includes dots, then it will be checked as the address without dots (it's the same for gmail.com), there is an additional field "email" without dots in the server's response:

 

https://api.cleantalk.org/?method_name=spam_check&auth_key=123456&email=1234.test.te@gmail.com

 

Response:

 

{"data":{"1234.test.te@gmail.com":{"appears":0,"sha256":"1cab88c5f6304f48ac75e8a175a0351a7d6bfd7fbd55d2f90eab96213dcdf639","disposable_email":0,"email":"1234testte@gmail.com"}}}

 

 

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" — the 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 minutes activity;
  • "frequency_time_1h" — 1 hour activity;
  • "frequency_time_24h" — 24 hours activity.
  • "network_type" — the category of using the address space.

 

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