Anti-Spam "check_message()" API method

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

It is part of the CleanTalk Anti-Spam API - a spam detection API you can call from any backend. Client libraries and integration examples are on the CleanTalk for developers page. To check registrations and forms without a message field, use check_newuser().

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

Limits and response time

Related methods

Code Examples

• curl
• Wget
• PHP (GitHub)
• Python (GitHub)
• Django (GitHub)
• NodeJS (GitHub)
• C# (GitHub)
• GoLang

FAQ

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": {
		"REFFERRER": "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.

Limits and response time

• Endpoint: https://moderate.cleantalk.org/api2.0, one HTTPS POST per form submission. No call limit - the number of checks is not throttled.
• Response time: about 0.1 second from Europe. Set a client timeout of 3 to 5 seconds.
• If the cloud does not answer: let the submission through. A missing verdict should never block a real customer.
• Database methods (spam_check(), email_check()) are different: they run on https://api.cleantalk.org, require a separate CleanTalk Database product key, and are limited to 100 calls per 60 seconds. An Anti-Spam key returns {"error_message":"Unknown access key...","error_no":6} there, and exceeding the limit returns {"error_message":"Calls limit exceeded.","error_no":10}.
• Authentication: your CleanTalk Access Key in the auth_key parameter.

Related methods

The check_message() spam detection API is one of several methods of the CleanTalk Anti-Spam API. Depending on what you need to check, use:

• check_newuser() - spam check for registrations, subscriptions and forms without a message field.
• check_bot() - tells whether a specific submission was made by a bot.
• spam_check() - checks an IP address or email against the CleanTalk spam database.
• email_check() - checks whether an email address actually exists.
• send_feedback() - sends the final verdict back to the cloud so the filter learns from your decisions.

Ready-made client libraries for PHP, Python, Ruby, C#, Perl, Laravel and Yii are listed on the CleanTalk for developers page.

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 curl

CLI example

curl -X POST https://moderate.cleantalk.org/api2.0 \
  -H "Content-Type: application/json" \
  -d '{
    "method_name": "check_message",
    "auth_key": "your_access_key",
    "message": "Buy cheap pills online",
    "sender_email": "stop_email@example.com",
    "sender_nickname": "John Doe",
    "sender_ip": "127.0.0.1",
    "js_on": 1,
    "submit_time": 15
  }'

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

}

FAQ

What is a spam detection API?

A spam detection API lets your backend send user-submitted content - a comment, review or form message - to a remote service that returns whether it is spam. CleanTalk's check_message() is a spam detection and spam filter API for user-generated content: you send the message and the sender data, and get an allow or deny decision back.

How does the check_message() spam filter API work?

You send an HTTPS POST with the message plus sender signals (email, IP, nickname) as JSON to the CleanTalk cloud. The API checks it against a global spam database and behavioral signals and returns allow=1 (legitimate) or allow=0 (spam), with the reason in the codes field. Authentication is done with your CleanTalk Access Key.

Is there a free anti-spam API?

Yes. CleanTalk offers a free trial, after which the Anti-Spam service continues on an annual plan - see pricing. The same Access Key powers all API methods.

Which programming languages are supported?

Any language that can send an HTTPS POST. The examples above cover curl, Wget, PHP, Python, Django, Node.js, C# and GoLang. For spam registration checks use the check_newuser() spam registration API method; for the full method list see the CleanTalk Anti-Spam API.

Related Links

Available features related to the method:

• CleanTalk's Personal Blacklist or Whitelist feature helps you block unwanted users and allow users who 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 registrations 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.