API Method "spam_check"

 

 

In order to use SPAM_CHECK method, you have to buy a separate license — 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 the existence of IP and e-mail records in our database for a long period of time.

It may differ from the result 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 the 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 the 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 for statistics 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
  • hosted_domains - 0|1 show list of hosted domains on an IPv4 address.

 

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&ip=127.0.0.1&date=2017-01-31

 

Example request with email hash:

https://api.cleantalk.org/?method_name=spam_check&auth_key=123456&email=email_08c2495014d7f072fbe0bc10a909fa9dca83c17f2452b93afbfef6fe7c663631

 

Example request with IP v4 hash:

https://api.cleantalk.org/?method_name=spam_check&auth_key=12345&ip=ip4_f46604ded89bbd0e8e478172a9a650f4825a763053ad2e3582c8286864ec4074

 

API returns JSON string, for example:

{"data":{"127.0.0.1":{"network_type":"unknown","country":"","appears":0,"frequency":0,"sha256":"12ca17b49af2289436f303e0166030a21e525d266e209267433801a8fd4071a0"},"stop_email@example.com":{"frequency":1001,"updated":"2021-02-22 12:06:14","spam_rate":0,"exists":1,"frequency_time_10m":0,"frequency_time_1h":0,"frequency_time_24h":0,"appears":1,"disposable_email":1,"sha256":"6d42ca0235d72b01a2b086ad53b5cfac24b5a444847fad70250e042d7ca8bf59"}}}

 

or for email hash:

{"data":{"email_08c2495014d7f072fbe0bc10a909fa9dca83c17f2452b93afbfef6fe7c663631":{"frequency":4,"updated":"2018-10-31 00:07:21","spam_rate":1,"exists":1,"frequency_time_10m":0,"frequency_time_1h":0,"frequency_time_24h":0,"appears":0,"disposable_email":1}}}

 

or for IP v4 hash:

{"data":{"ip4_f46604ded89bbd0e8e478172a9a650f4825a763053ad2e3582c8286864ec4074":{"frequency":13626,"updated":"2019-05-15 05:01:23","spam_rate":1,"network_type":"hosting","country":"GB","frequency_time_10m":0,"frequency_time_1h":0,"frequency_time_24h":0,"appears":1}}}

 

 

Responses Explanation:

data — array with checked records, which contains them in the following format: "record":{array of check results}.

An array of check results may contain the next fields:

  • appears — the marker that defines the record status in the blacklists 0|1 (shows if the record is blacklisted right now),
  • sha256 — address sha256 hash
  • network_type — special net-type if any (there might be new types in the future):
  • 'hosting' - IP address belongs to the network hosting company
  • 'public' - IP address belongs to ISP but this network or AS has a hight spam activity
  • 'paid_vpn' - IP address belongs to VPN Service Provider
  • 'tor' - IP address belongs to Tor Exit Nodes (very spam active addresses)
  • 'unknown' - IP address has no special type for now
  • empty value - exactly like 'unknown'
  • spam_rate — a rating of spam activity from 0 to 100%. 100% means certain spam (the ratio of blocked requests to all),
  • country — letter country code of the IP, in ISO 3166-1 alpha-2
  • exists — check email for existence (0 - not exists, 1 - exists),
  • disposable_email — check email for disposable (0 - normal, 1 - disposable),
  • frequency — is a number of websites that reported spam activity of the record. It can be from 0 up to 9999 (shows total activity from the first time the record was caught),
  • frequency_time_10m — 10-minute activity (shows how many attempts of spam attacks were caught), 
  • frequency_time_1h — 1-hour activity (shows how many attempts of spam attacks were caught),
  • frequency_time_24h — 24-hour activity (shows how many attempts of spam attacks were caught),
  • in_antispam — IP address found in Anti-Apam blacklist (0 - not found, 1 - found),
  • in_security — IP address found in security blacklist (brute-force) (0 - not found, 1 - found),
  • domains_count — number of domains found on IPv4 address.
  • domains_list - list of hosted domains/sites on IPv4 address. Method shows first 1000 domains. To get full list of domains please use method domains_list().

In the case of 'date' parameter response contains results on a given date only. You can check by POST request up to 1000 records at one time.

You can check email for existence and disposable only with the GET request and only 1 address at one time.

If the record hasn't been showing any activity for 14 days it will be removed from blacklists but the history will stay.

 

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}

The current calls limit is 100 per 60 seconds.

 

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

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

The current data elements limit is 1000.

The recommended timeout is no more than 180 seconds.

 

Analysis and processing errors are returned individually for each record. Example:

{"data":{"10.0.0.3":{"error":"Database error"}}}

'Database error' informs about data retrieving problem - slow database server answer and so on. So all you need is to repeat the request after a few minutes.

{"data":{"10.0.0.266":{"error":"Can't check this record: Wrong format"}}}

There might be new error descriptions in the future.

 

Notice: if data are 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 an address without dots (it's the same for gmail.com), there is an additional field "email" without dots in 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 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}

Explanation:

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

 

Example:

"ip":{"appears":0}

Explanation:

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

 

Example:

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

Explanation:

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

 

 

Nginx Anti-Spam Module

 

CleanTalk offers the possibility to use the anti-spam service on the webserver level. We have developed our anti-spam module for Nginx: https://github.com/CleanTalk/nginx-cleantalk-service

After installing the CleanTalk anti-spam module for Nginx on your web server, each POST request will be checked for spam with the CleanTalk API meaning that every spam request will be blocked. Your statistics of the CleanTalk anti-spam module for Nginx is always available in your CleanTalk Dashboard.

 


Perhaps it would also be interesting