CleanTalk Anti-Spam "check_message" API method description

This method is the best to use on forms that contain User-generated content (UGC) like a comment, review, or contact form.

1. Collect web-form data.
2. Send data JSON via a POST request to https://moderate.cleantalk.org/api2.0.
3. Parse the response and make a decision.

Request

• Data JSON Example
• Data Processing
• Required Parameters
• Additional parameters

Response

• Response example
• Response Explanation

Code Examples

• Wget
• PHP
• Python
• NodeJS
• C#
• GoLang

Related Links

Request

Data JSON Example

{
	"method_name":"check_message",
	"auth_key":"your_access_key",
	"sender_email":"stop_email@example.com",
	"sender_nickname":"John Doe",
	"sender_ip":"127.0.0.1",
	"event_token":"sha_256_string_of_event_token"
	"submit_time":15,
	"sender_info": {
		"REFERRER": "https:/referrer-site.com",
		"USER_AGENT": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3835.0 Safari/537.36"
		},
	"message": "Hello I am a spammer visit this https://badlinkexample.com"
}

Data Processing

Necessary information about the data processing

Required Parameters

The method will not work without these parameters 

Additional parameters

These parameters are necessary for filtering spam

Response

Response example

The server's response is independent of the platform.

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

Response Explanation

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: "DENIED EMAIL_NOT_EXISTS" 

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

Code Examples

To integrate CleanTalk with your project, please use our official libraries.
All examples are available in GitHub repositories (see README files for usage):

• PHP: CleanTalk/php-antispam
• Python: CleanTalk/python-antispam
• Django: CleanTalk/django-antispam-no-recaptcha-captcha
• Node.js: westtrade/cleantalk
• C#: CleanTalk/csharp-antispam

Using Wget

CLI example

wget -O- --post-data='{"method_name":"check_message","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 GoLang

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"io/ioutil"
	"net/http"
	"strings"
)

var authKey string = "enter_your_key"
var configUrg string = "http://moderate.cleantalk.org/api2.0/"
var agent string = "golang-api"

type messageInputData struct {
	MethodName     string `json:"method_name"`
	AuthKey        string `json:"auth_key"`
	Agent          string `json:"agent"`
	SenderEmail    string `json:"sender_email"`
	SenderIp       string `json:"sender_ip"`
	SenderNickname string `json:"sender_nickname"`
	JsOn           uint   `json:"js_on"`
	SubmitTime     uint   `json:"submit_time"`
	AllHeaders     string `json:"all_headers"`
	Message        string `json:"message"`
	SenderInfo     string `json:"sender_info"`
	ResponseLang   string `json:"response_lang"`
	PostInfo       string `json:"post_info"`
	StoplistCheck  uint   `json:"stoplist_check"`
}

type MessageResultData struct {
	Version       string `json:"version"`
	Inactive      uint   `json:"inactive"`
	JsDisabled    uint   `json:"js_disabled"`
	Blacklisted   string `json:"blacklisted"`
	Comment       string `json:"comment"`
	Codes         string `json:"codes"`
	FastSubmit    uint   `json:"fast_submit"`
	Id            string `json:"id"`
	AccountStatus uint   `json:"account_status"`
	Allow         uint   `json:"allow"`
	StopQueue     uint   `json:"stop_queue"`
	Spam          uint   `json:"spam"`
}

func main() {
	inputData := messageInputData{
		MethodName:     "check_message",
		AuthKey:        authKey,
		Agent:          agent,
		SenderEmail:    "stop_email@example.com",
		SenderIp:       "192.168.0.1",
		SenderNickname: "testuser",
		JsOn:           1,
		SubmitTime:     5,
		Message:        "Test message",
	}

	resultData, err := CheckMessage(inputData)
	if err != nil {
		fmt.Println(err.Error())
		return
	}
	if resultData.Allow == 1 {
		fmt.Println(fmt.Sprintf("User allowed. Reason %s", resultData.Comment))
		return
	}
	fmt.Println(fmt.Sprintf("User forbidden. Reason %s", resultData.Comment))
}

func CheckMessage(inputData messageInputData) (MessageResultData, error) {
	inputDataBytes, err := json.Marshal(inputData)
	var resultData MessageResultData
	if err != nil {
		return resultData, err
	}
	var body io.Reader = strings.NewReader(string(inputDataBytes))
	req, err := http.NewRequest(http.MethodPost, configUrg, body)
	if err != nil {
		return resultData, err
	}
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		return resultData, err
	}
	defer resp.Body.Close()

	answer, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		return resultData, err
	}
	err = json.Unmarshal(answer, &resultData)
	return resultData, nil

}

Related Links

Available features related to the method:

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

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