Метод проверки spam_check - проверка по чёрным спискам

{"data":{"127.0.0.1":{"domains_count":0,"domains_list":null,"spam_rate":0,"submitted":"2021-08-10 04:32:53","updated":"2021-10-14 10:58:10","frequency":9,"in_antispam":0,"in_security":0,"appears":0,"network_type":"good_bots","country":null,"sha256":"12ca17b49af2289436f303e0166030a21e525d266e209267433801a8fd4071a0"},"stop_email@example.com":{"frequency":3,"submitted":"2021-01-01 02:25:06","updated":"2021-01-15 03:01:02","spam_rate":1,"appears":1,"disposable_email":1,"exists":null,"sha256":"6d42ca0235d72b01a2b086ad53b5cfac24b5a444847fad70250e042d7ca8bf59"}}}

Для хэша адреса email:

{"data":{"email_08c2495014d7f072fbe0bc10a909fa9dca83c17f2452b93afbfef6fe7c663631":{"frequency":4,"submitted":"2018-10-16 01:53:49","updated":"2021-04-15 08:49:53","spam_rate":1,"exists":1,"appears":0,"disposable_email":1}}}

Для хэша адреса IP v4:

{"data":{"ip4_f46604ded89bbd0e8e478172a9a650f4825a763053ad2e3582c8286864ec4074":{"domains_count":0,"domains_list":null,"spam_rate":1,"submitted":"2018-07-29 07:09:45","updated":"2019-09-25 15:33:00","frequency":13627,"in_antispam":0,"in_security":0,"appears":0,"network_type":"hosting","country":"GB"}}}

Расшифровка ответа:

data - обычно массив проверенных записей представлен в следующем формате: "record": {массив проверенных результатов}. Иногда ответ "data" возвращает строку "In progress", это означает, что параллельный PHP-процесс работает с точно такими же параметрами - auth_key, method_name и records.

Важно! Ответ "In progress" является значимым его следует учитывать, так как если вызов API содержит большое количество элементов, то они могут быть проверены частично и выдастся ответ "In progress". Только при повторном вызове будут проверены все оставшиеся элементы.

Массив с проверенными записями содержит следующие поля:

• appears - флаг присутствия в черных списках (показывает блокировку на настоящий момент),
• sha256 - хэш sha256 адреса,
• network_type - принадлежность к определенному типу сети (возможно в дальнейшем добавятся новые типы):

• hosting - адрес IP принадлежит сети хостинг провайдера
• public - адрес IP принадлежит интернет провайдеру, но данная подсеть или автономная система имеют высокую спам активность
• paid_vpn - адрес IP принадлежит провайдеру VPN сервиса
• tor - адрес IP принадлежит нодам сети Tor (очень спам активные адреса)
• unknown - адрес IP пока не имеет специального типа

• spam_rate - спам-рейтинг от 0 до 100%. 100 означает точно спам (отношение спам запросов к общему количеству запросов). Параметр "spam_rate" может иметь значение от 0 до 1:  "spam_rate": "1" — 100% запросов было спамом, "spam_rate": "0,75" — 75% запросов было заблокировано как спам,
• submitted - дата и время первой спам-активности,
• updated - дата и время последнего обновления статуса,
• country - буквенный код страны, которой принадлежит IP адрес, в формате ISO 3166-1 alpha-2,
• exists - существует ли данный email (0 - не существует, 1 - существует, null - пустой статус, адрес не находится в списках в данный момент),
• disposable_email - является ли данный email временным (0 - обычный, 1 - временный, null - пустой статус, адрес не находится в списках в данный момент),
• frequency - количество сайтов отметивших запись как спам. Может быть от 0 до 9999 (показывает всю активность с самого начала обнаружения адреса)
  
• spam_frequency_24h - это количество спам запросов, которые были заблокированы анти-спам сервисом за последние 24 часа.
  
• in_antispam - IP адрес найден в чёрном списке анти-спам,
• in_antispam_previous — предыдущий статус в чёрном списке анти-спам. Может показать была ли запись в чёрном списке ранее (0 - не была в ЧС, 1 - была в ЧС, NULL - нет изменений)
• in_antispam_updated — Дата измения статуса в чёрном списке анти-спам (NULL - нет изменений),
• in_security - IP адрес найден в чёрном списке безопасности (brute-force),
• domains_count - число доменов, найденных на IP адресе.

В случае указания параметра "date" данные ответа приводятся только на указанную дату. Посредством POST запроса можно за один раз отправить на проверку до 1000 записей.

Проверку адреса email на существование и одноразовость (временный адрес) можно осуществить только с помощью GET запроса и только 1 адрес за раз. 

Если не было активности с адреса в течение 14 дней, то запись удаляется из черных списков, но вся история остаётся.

Вы можете отправить несколько записей для теста за 1 раз, для этого используйте POST параметры:

• data - строка с записями для проверки разделенная ','.

Например,

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

Ответ:

{"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}}}

Ограничения

Если вы превысите максимальное количество вызовов, API вернет ошибку, например,

{"error_message":"Calls limit exceeded.","error_no":10}

Сейчас максимальное количество вызовов установлено в 100 вызовов за 60 секунд.

Если вы превысите максимальное количество элементов данных в методе spam_check вызовов, API вернет ошибку, например,

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

Сейчас максимальное количество элементов данных установлено в 1000.

Рекомендуемый таймаут - не более 180 секунд.

Ошибки при анализе и обработке данных возвращаются индивидуально для каждой записи, например,

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

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

Примечание: Если в запросе передается дата, то время выполнения этого запроса будет немного увеличено.

Особенности проверки адресов gmail.com

Если почтовый адрес из gmail.com и содержит точки, то проверка выполняется для почты без точек (т.к. это одно и то же для gmail.com), вывод дополняется полем "email" без точек:

https://api.cleantalk.org/?method_name=spam_check&auth_key=123456&email=1234.test.te@gmail.com

Ответ:

{"data":{"1234.test.te@gmail.com":{"appears":0,"sha256":"1cab88c5f6304f48ac75e8a175a0351a7d6bfd7fbd55d2f90eab96213dcdf639","disposable_email":0,"email":"1234testte@gmail.com"}}}

Описание нескольких примеров ответов API

Ниже вы можете увидеть разбор и описание параметров для возможных вариантов ответа сервера, таких как:

• "appears" - флаг присутствия в черных списках;
• "spam_rate" - спам-рейтинг от 0 до 100%. 100 означает точно спам (отношение спам запросов к общему количеству запросов). Параметр "spam_rate" может иметь значение от 0 до 1:  "spam_rate": "1" — 100% запросов было спамом, "spam_rate": "0,75" — 75% запросов было заблокировано как спам.
• "frequency" - количество сайтов, которые сообщили о спам активности записи;
• "network_type" - категория использования адресного пространства;
• "submitted" - дата и время первой спам-активности;
• "updated" - дата и время последнего обновления статуса;
• "in_antispam" - IP адрес найден в чёрном списке анти-спам;
• "in_security" - IP адрес найден в чёрном списке безопасности (brute-force).

Пример:

"ip":{"appears":1}

Объяснение:

• IP находится в черном списке;

Пример:

"ip":{"appears":0}

Объяснение:

• IP не находится в черном списке;

Пример:

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

Объяснение:

• "appears": "0" - IP не находится в черном списке;
• "frequency": "15" - 15 сайтов сообщили о спам активности этого IP.
  
  

Пример:

"ip":{ "appears":"0","spam_rate":"1","frequency":"1"}

Объяснение:

• "appears": "0" - IP не находится в черном списке;
• "spam_rate": "1" - был 1 запрос и он был определен как спам активный;
• "frequency": "1" - 1 сайт сообщил о спам активности этого IP.;
  
  

Пример:

"email":{ "appears":"0","spam_rate":"1","frequency":"1","exists":"1"}

Объяснение:

• "appears": "0" -  email не находится в черном списке;
• "spam_rate": "1" - был 1 запрос и он был определен как спам активный;
• "frequency": "1" - 1 сайт сообщил о спам активности этого email;
• "exists": "1" - реальный адрес электронной почты, который присутствует на почтовом сервере.

Анти-спам модуль для Nginx

CleanTalk предлагает возможность использовать антиспам сервис на уровне сервера, мы разработали антиспам модуль для Nginx.
https://github.com/CleanTalk/nginx-cleantalk-service

После установки Анти-спам модуля от CleanTlak на Nginx сервер, все POST запросы будут проверяться на спам через CleanTalk API и спам запросы будут блокироваться. Статистика работы Анти-спам модуля для Nginx доступна в панели управления CleanTalk.

Условия фильтрации

Вы можете комбинировать значения параметров для оценки спам-активности адреса. 

Пример: "appears" — это основной параметр на который вы можете ориентироваться. Ответ "appears": "1" означает, что проверяемый адрес в данный момент находится в черных списках. Но адрес может и не быть в черных списках в данный момент и "appears" будет равен "0". Поэтому вы можете использовать дополнительные параметры API.

Что можно считать спамом:

• Если адрес имеет значение "appears": "1";
• Если адрес имеет значение "appears": "0" и "spam_rate" больше чем "0,7";
• Если адрес имеет значение "appears": "0" и "spam_rate" больше чем "0,5", а дата последней спам активности была не более 30 дней назад;
• Если адрес имеет значение "appears": "0", "spam_rate": "1", "frequency": "5" и больше, a "updated" не более 30 дней назад;
• Если адрес имеет значение "appears": "0", "frequency": "200" и больше, а "updated" не более 90 дней назад.

Вы должны оценить необходимые параметры и их комбинацию. Если вы хотите оценивать спам-активность только тех адресов, которые в данный момент находятся в черных списках, то достаточно использовать параметр "appears".