API Method "spam_check_cms" CMS-related version of spam_check

This method performs short Blacklist Database checking using antispam key. It returns only one field "appears".

Call Requires GET Parameters:

• method_name — should be 'spam_check_cms'
• auth_key — Antispam key. To obtain a key please get an account here: https://cleantalk.org/register?platform=antispam

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)

Example request with IP:

https://api.cleantalk.org/?method_name=spam_check_cms&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_cms&auth_key=123456&ip=127.0.0.1&date=2017-01-31

API returns JSON string, for example:

{"data":{"127.0.0.1":{"appears":0}}}

Responses Explanation:

data — usually an array of the checked records presented in the following format: "record":{array of checked results}. Sometimes the response 'data' returns a string 'In progress', it means that a concurrent PHP-process is working with exactly the same parameters — auth_key, method_name and records.

Important! The response "In progress" has a significant meaning and it has to be counted. If your API call has a lot of elements then they will be checked partially in one go and you will get the "In progress" response. And only the next API call will check the rest of the elements.

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),

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_cms\&auth_key=123456

Response:

{"data":{"stop_email@example.com":{"appears":1},"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_cms&auth_key=123456&email=1234.test.te@gmail.com

Response:

{"data":{"1234.test.te@gmail.com":{"appears":0,}}}

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;

Example:

"ip":{"appears":1}

Explanation:

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

Example:

"ip":{"appears":0}

Explanation:

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