API Method "check_newuser"

Required Parameters:

method_name — must be 'check_newuser';
auth_key — Access key. To obtain a key please get an account here
sender_email — e-mail you want to check for spam;
sender_ip — IP you want to check for spam;
js_on — is JavaScript enabled in a user's browser or not;
submit_time — form submitting time in seconds.

Here is the list of the necessary parameters that heavily affect filtration. Most of the sent requests will be marked as spam without them:

all_headers — HTTP-request headers (JSON encoded);
sender_nickname — nickname you want to check for spam;
sender_info — information about the sender, should be JSON encoded, next fields are mandatory:

REFFERRER — content of $_SERVER['HTTP_REFERER']
USER_AGENT — content of $_SERVER['HTTP_USER_AGENT']

Additional parameters:

Sending these parameters will improve filtration.

sender_info — any additional information about the sender, should be JSON encoded, see example below;
response_lang — API response language;
tz — sender's timezone;
phone — sender's phone number;

Examples:

Using Wget:

wget -O- --post-data='{"method_name":"check_newuser","auth_key":"your_acccess_key","sender_email":"stop_email@example.com","sender_nickname":"John Doe","sender_ip":"127.0.0.1","js_on":1,"submit_time":15}' https://moderate.cleantalk.org/api2.0

Using PHP:

Download CleanTalk library here. Library folder must be placed in the same path as the PHP file.

Also, you can install the library via composer.

<?php
session_start();
 
require_once (dirname(__FILE__) . '/lib/Cleantalk.php');
require_once (dirname(__FILE__) . '/lib/CleantalkRequest.php');
require_once (dirname(__FILE__) . '/lib/CleantalkResponse.php');
require_once (dirname(__FILE__) . '/lib/CleantalkHelper.php');
 
// Take params from config
$config_url = 'http://moderate.cleantalk.org/api2.0/';
$auth_key = 'enter_your_key'; // Set Cleantalk auth key
 
if (count($_POST))
{
        $sender_nickname = 'John Dow';
        if (isset($_POST['login']) && $_POST['login'] != '')
                $sender_nickname = $_POST['login'];
 
        $sender_email = 'stop_email@example.com';
        if (isset($_POST['email']) && $_POST['email'] != '')
                $sender_email = $_POST['email'];
 
        $sender_ip = null;
        if (isset($_SERVER['REMOTE_ADDR']))
                $sender_ip = $_SERVER['REMOTE_ADDR'];
 
        $js_on = 0;
        if (isset($_POST['js_on']) && $_POST['js_on'] == date("Y"))
                $js_on = 1;
 
// The facility in which to store the query parameters
$ct_request = new /lib/CleantalkRequest();
$ct_request->auth_key = $auth_key;
$ct_request->agent = 'php-api';
$ct_request->sender_email = $sender_email;
$ct_request->sender_ip = $sender_ip;
$ct_request->sender_nickname = $sender_nickname;
$ct_request->js_on = $js_on;
$ct_request->submit_time = time() - (int) $_SESSION['ct_submit_time'];
 
//Additional parameters.
$ct = new \lib\Cleantalk();
$ct->server_url = $config_url;
 
//Check
$ct_result = $ct->isAllowUser($ct_request);
        if ($ct_result->allow == 1)
                echo 'User allowed. Reason ' . $ct_result->comment;
        else
                echo 'User forbidden. Reason ' . $ct_result->comment;
        echo '<br /><br />';
}
else
        $_SESSION['ct_submit_time'] = time();
?>

HTML code:

<form method="post">
        <label for="login">Login:<label>
        <input type="text" name="login" id="login" /> <br />
        <label for="email">Email:<label>
        <input type="text" name="email" id="email" value="" /> <br />
        <input type="hidden" name="js_on" id="js_on" value="0" />
        <input type="submit" />
        </form>
<script type="text/javascript">
var date = new Date(); document.getElementById("js_on").value = date.getFullYear();
</script>

Submit_time and js_on parameters are very important for checking. Submit_time is the difference between submitting form time and page accessing time. Js_on can be calculated by evaluating some JavaScript code in browser and comparing with reference value on server side.

Example of additional parameters usage:

$sender_info = array(
        'page_url' =>htmlspecialchars(@$_SERVER['SERVER_NAME'].@$_SERVER['REQUEST_URI']),
        'REFFERRER' => htmlspecialchars(@$_SERVER['HTTP_REFERER']),
        'USER_AGENT' => htmlspecialchars(@$_SERVER['HTTP_USER_AGENT']),
        'fields_number' => sizeof($_POST),
);
$sender_info = json_encode($sender_info);
        if ($sender_info === false) $sender_info = '';
$ct_request->sender_info = $sender_info;
$ct_request->phone = '+1 123-456-78-90';
$ct_request->all_headers = json_encode(apache_request_headers());

More info can be found on our GitHub.

Response:

Server's response is independent of the platform.

{
"version" : "7.47",
"inactive" : 0,
"js_disabled" : 0,
"blacklisted" : 1,
"comment" : "*** Forbidden. Sender blacklisted. ***",
"codes" : "FORBIDDEN BL",
"fast_submit" : 0,
"id" : "5a49267e202169b3a4d9ddefee190065",
"account_status" : 1,
"allow" : 0
}

Explanation:

js_disabled — JavaScript is disabled;
blacklisted — sender is in the CleanTalk Blacklists;
comment — comment of server's decision or of other errors (wrong Access key etc.);
codes — answer codes.
fast_submit — to fast form submitting;
id — message ID (helpful for our support),
account_status — is account enabled or not (0 or 1);
allow — is message allowed (1) or not (0);

The rest is information flags for displaying appropriate messages to site visitors.

In the server response code, you can also see the result of checking an email address for existence. If a blocked request contains a non-existent e-mail address, you will see the next text in the API response code field: "FORBIDDEN EMAIL_NOT_EXISTS"

Please note, this code will be displayed only if a non-existent email is the main reason for blocking.

You could see the details of the codes at the bottom of this article: https://cleantalk.org/help/api-without.

Available features:

CleanTalk's Personal Blacklist or Whitelist feature helps you to block unwanted users and to allow users that were recognized as spammers.
Stop-Word feature allows you to block comments and nicknames which contain any word from your Stop-Word List.
Country Blacklist allows you to block all comments and registration coming from selected countries.

Notice: Stop-Word and Country Blacklist features are available after purchasing our Extra Package. Go to your Renewal License Page to see the details.

Method CHECK_NEWUSER should be used to check registrations for spam. For other purposes you could use other methods:

check_message (requires Standard Anti-Spam License) — API spam filter to check Posts/comments.
send_feedback (requires Standard Anti-Spam License) — Send feedback to CleanTalk.
spam_check (requires Blacklist API License) — Bulk IP and e-mail check for spam activity.
backlinks_check (requires Blacklist API License) — Mass check for backlinks in spam comments.
Nginx Anti-Spam Module - check all POST requests for spam
Universal Anti-Spam Plugin - this plugin can be installed on any custom websites or CMS.