Удалить из CRM дела письма mail.message.removecrmactivity

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Scope: mail

Кто может выполнять метод: пользователь с правом «Настройка связи с CRM», полным доступом к письму и правом удалять дела CRM

Метод относится к REST 3.0. Особенности вызова и формат ответа новой версии API описаны в обзоре REST 3.0.

Метод mail.message.removecrmactivity удаляет из CRM дела, созданные из письма.

Параметры метода

Обязательные параметры отмечены *

Название
тип

Описание

messageId*
integer

Идентификатор письма.

Идентификатор можно получить методом mail.message.list

Метод удаляет только те дела, которые пользователь может удалить по правам CRM. Остальные дела остаются в CRM вместе со связью с письмом, в ответе в этом случае complete: false.

Если удалены все дела, метод добавляет адрес отправителя входящего письма в список исключений CRM, чтобы новые письма от него не попадали в CRM. Адрес добавляется, только если у пользователя есть право изменять список исключений.

Полный доступ к письму есть у пользователей с доступом к почтовому ящику. Если письмо доступно пользователю только через связанную задачу, чат, событие или сообщение Ленты новостей, метод вернет ошибку.

Примеры кода

Как использовать примеры в документации

Вызов нового API отличается добавлением параметра /api/ в запросе:

https://{адрес_установки}/rest/api/{id_пользователя}/{токен_вебхука}/mail.message.removecrmactivity

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"messageId":15}' \
https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/mail.message.removecrmactivity
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"messageId":15,"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/api/mail.message.removecrmactivity
// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'

declare const $b24: B24Frame

type RemoveCrmActivityResult = {
  result: boolean
  deletedCount: number
  totalCount: number
  complete: boolean
}

try {
  const response = await $b24.actions.v3.call.make<RemoveCrmActivityResult>({
    method: 'mail.message.removecrmactivity',
    params: {
      messageId: 15,
    },
    requestId: Text.getUuidRfc4122()
  })

  // The payload is available only on a successful response
  if (!response.isSuccess) {
    console.error(response.getErrorMessages().join('; '))
  } else {
    const result = response.getData()!.result
    console.info('Удалено дел:', result.deletedCount, 'из', result.totalCount, 'все удалены:', result.complete)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
  async function removeCrmActivity() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.actions.v3.call.make({
        method: 'mail.message.removecrmactivity',
        params: {
          messageId: 15,
        },
        requestId: B24Js.Text.getUuidRfc4122()
      })

      // The payload is available only on a successful response
      if (!response.isSuccess) {
        console.error(response.getErrorMessages().join('; '))
        return
      }

      const result = response.getData().result
      console.info('Удалено дел:', result.deletedCount, 'из', result.totalCount, 'все удалены:', result.complete)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', removeCrmActivity)
</script>
from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.mail.message.removecrmactivity(
        message_id=15,
    ).response
    result = bitrix_response.result
    print(result)
except BitrixAPIError as error:
    print(
        "Ошибка Bitrix API",
        f"error: {error.error}",
        f"error_description: {error.error_description}",
        sep="\n",
    )
except BitrixSDKException as error:
    print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
    print(f"Непредвиденная ошибка: {error}")

SDK пока не поддерживает вызовы по адресу /rest/api/. Используйте прямой HTTP-запрос, например через cURL или fetch.

try {
    $response = $b24Service
        ->core
        ->call(
            'mail.message.removecrmactivity',
            [
                'messageId' => 15
            ]
        );

    $result = $response
        ->getResponseData()
        ->getResult();

    echo 'Success: ' . print_r($result, true);
} catch (Throwable $e) {
    error_log($e->getMessage());
    echo 'Error: ' . $e->getMessage();
}

SDK пока не поддерживает вызовы по адресу /rest/api/. Используйте прямой HTTP-запрос, например через cURL или fetch.

BX24.callMethod(
    'mail.message.removecrmactivity',
    {
        messageId: 15
    },
    function(result){
        console.info(result.data());
        console.log(result);
    }
);

SDK пока не поддерживает вызовы по адресу /rest/api/. Используйте прямой HTTP-запрос, например через cURL или fetch.

require_once('crest.php');

$result = CRest::call(
    'mail.message.removecrmactivity',
    [
        'messageId' => 15
    ]
);

echo '<PRE>';
print_r($result);
echo '</PRE>';
// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "mail.message.removecrmactivity", b24.Params{
	"messageId": 15,
})
if err != nil {
	return fmt.Errorf("mail.message.removecrmactivity: %w", err)
}

var item struct {
	Result       bool `json:"result"`
	DeletedCount int  `json:"deletedCount"`
	TotalCount   int  `json:"totalCount"`
	Complete     bool `json:"complete"`
}
if err := json.Unmarshal(res.Result, &item); err != nil {
	return fmt.Errorf("разбор ответа: %w", err)
}
fmt.Println(item.DeletedCount, item.TotalCount, item.Complete)

Обработка ответа

HTTP-статус: 200

{
    "result": {
        "result": true,
        "deletedCount": 1,
        "totalCount": 1,
        "complete": true
    },
    "time": {
        "start": 1779819678,
        "finish": 1779819678.84803,
        "duration": 0.8480300903320312,
        "processing": 0,
        "date_start": "2026-05-26T21:21:18+03:00",
        "date_finish": "2026-05-26T21:21:18+03:00",
        "operating_reset_at": 1779820278,
        "operating": 0
    }
}

Возвращаемые данные

Название
тип

Описание

result
object

Объект с результатом удаления

result.result
boolean

При успешном ответе всегда true

result.deletedCount
integer

Сколько дел удалено

result.totalCount
integer

Сколько дел CRM было создано из письма.

result.complete
boolean

Удалены ли все дела. Возможные значения:

  • true — удалены все дела письма
  • false — часть дел осталась в CRM, у пользователя нет прав их удалить

time
time

Информация о времени выполнения запроса

Сейчас Битрикс24 возвращает только result.result, без счетчиков deletedCount, totalCount и complete. Так метод отвечает, в том числе если у письма нет дел CRM. Чтобы проверить результат, получите письмо методом mail.message.get и посмотрите связи с типом crm в поле bindings.

Обработка ошибок

HTTP-статус: 400

{
    "error": {
        "code": "BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION",
        "message": "Ошибка при валидации объекта запроса",
        "validation": [
            {
                "message": "Parameter \"messageId\" is required.",
                "field": "MISSING_MESSAGE_ID"
            }
        ]
    }
}

Название
тип

Описание

error.code
string

Строковый код ошибки. Используйте для идентификации типа исключения

error.message
string

Текстовое описание ошибки

error.validation
array

Массив c деталями ошибки. Присутствует только в ошибках валидации данных BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION

error.validation[].field
string

Название поля, в котором возникла ошибка валидации

error.validation[].message
string

Описание ошибки, связанной с указанным полем

Возможные коды ошибок

Ошибки валидации запроса

Код ошибки: BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION

В колонке «Поле» — значение field из элемента validation. Метод передает в нем код причины, а не имя параметра. У ошибок без кода field в ответе нет.

Поле

Описание ошибки

Как исправить

MISSING_MESSAGE_ID

Parameter "messageId" is required.

messageId не передан, не является числом или меньше 1. Передайте идентификатор письма — положительное целое число

-

Установите модуль CRM

В Битрикс24 не установлен модуль CRM

MAIL_MESSAGE_CRM_ACCESS_DENIED

Нет доступа к CRM

У пользователя нет права «Настройка связи с CRM» в правах доступа почты. Выдайте право или вызовите метод от имени другого пользователя

-

Сообщение удалено или перемещено в другую папку

Письма с таким messageId нет или у пользователя нет к нему доступа. Проверьте идентификатор методом mail.message.list

MAIL_MESSAGE_CRM_ACCESS_DENIED

Access denied: full access to the message is required

Письмо доступно пользователю только через связанный объект. Вызовите метод от имени пользователя с доступом к почтовому ящику

MAIL_MESSAGE_CRM_ACCESS_DENIED

Access denied: cannot delete CRM activity

У пользователя нет права удалить ни одно из дел письма. Проверьте права пользователя на удаление дел в CRM

Статусы и коды системных ошибок

HTTP-статус: 4xx, 5xx

Описанные ниже ошибки возвращает сам REST API, а не логика конкретного метода. Они могут прийти в ответ на любой метод.

Статус

Код
Текст ошибки

Описание

500

INTERNAL_SERVER_ERROR
Internal server error

Возникла внутренняя ошибка сервера. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24

500

ERROR_UNEXPECTED_ANSWER
Server returned an unexpected response

Сервер вернул неожиданный ответ. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24

503

QUERY_LIMIT_EXCEEDED
Too many requests

Превышен лимит на интенсивность запросов

429

OPERATION_TIME_LIMIT
Method is blocked due to operation time limit

Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически, когда накопленное время выполнения метода перестает превышать лимит

401

NO_AUTH_FOUND
Wrong authorization data

В запросе нет авторизационных данных: не передан ни access-токен, ни код вебхука

401

INVALID_REQUEST
Https required

Методы вызываются только по протоколу HTTPS

401

OVERLOAD_LIMIT
REST API is blocked due to overload

REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка. Чтобы ее снять, обратитесь в техническую поддержку Битрикс24

401

ACCESS_DENIED
REST is available only on commercial plans

REST API доступен только на коммерческих тарифах. У вебхука текст ошибки другой — REST is available only by subscription

403

FEATURE_NOT_AVAILABLE_ON_CURRENT_PLAN
Функция недоступна на текущем тарифе.

Приложение Маркетплейса заблокировано, потому что число установленных приложений превышает лимит тарифа. События такому приложению не доставляются. Приложения, освобожденные от лимита, не блокируются

401

INVALID_CREDENTIALS
Invalid request credentials

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

404

ERROR_METHOD_NOT_FOUND
Method not found!

Метод с таким именем не найден. Имя написано с ошибкой, метода нет в REST API или он недоступен без нужного скоупа

401

insufficient_scope
The request requires higher privileges than provided by the webhook token

Запрос требует более широких прав, чем есть у токена: у вебхука это выданные ему права, у приложения — скоуп. У приложения текст ошибки заканчивается на provided by the access token

401

expired_token
The access token provided has expired

Срок действия access-токена истек

401

user_access_error
The user does not have access to the application

Приложение установлено, но администратор Битрикс24 открыл доступ к нему только конкретным пользователям

403

PORTAL_DELETED
Portal was deleted

Публичная часть сайта закрыта. Чтобы открыть ее на коробочной установке, отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

Продолжите изучение