Для AI-агентов: markdown этой страницы — /docs-content/mail/messages/move.md индекс документации — /llms.txt

Переместить письма

POST /v1/mail/messages/move

Выполняет массовое действие над письмами: перемещает в папку, помечает как спам или удаляет.

Поля запроса (body)

Поле Тип Обяз. Описание
messageIds array of integers да Идентификаторы писем
action string да Действие: move — переместить в папку, spam — пометить как спам, delete — удалить
folder string условно Целевая папка. Обязателен при action: "move"

Примеры

curl — личный ключ

Terminal 
curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  https://vibecode.bitrix24.tech/v1/mail/messages/move \
  -d '{
    "messageIds": [1234],
    "action": "move",
    "folder": "INBOX"
  }'

curl — OAuth-приложение

Terminal 
curl -X POST \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  https://vibecode.bitrix24.tech/v1/mail/messages/move \
  -d '{
    "messageIds": [1234],
    "action": "move",
    "folder": "INBOX"
  }'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/mail/messages/move', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    messageIds: [1234],
    action: 'move',
    folder: 'INBOX',
  }),
})
const data = await res.json()
console.log(data.data.movedCount)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/mail/messages/move', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    messageIds: [1234],
    action: 'move',
    folder: 'INBOX',
  }),
})
const data = await res.json()

Поля ответа

Поле Тип Описание
success boolean true при успешном выполнении запроса
data.success boolean true при успешном выполнении действия
data.movedCount integer Количество обработанных писем
data.action string Выполненное действие — move, spam или delete

Пример ответа

JSON 
{
  "success": true,
  "data": {
    "success": true,
    "movedCount": 1,
    "action": "move"
  }
}

Пример ответа при ошибке

400 — недопустимое значение action:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Ошибка при валидации объекта запроса",
    "validation": [
      {
        "field": "INVALID_ACTION",
        "message": "Parameter \"action\" must be \"move\", \"spam\", or \"delete\"."
      }
    ]
  }
}

Ошибки

HTTP Код Описание
400 INVALID_PARAMS Значение action не из допустимых — validation[].field равен INVALID_ACTION
400 INVALID_PARAMS Не передан messageIds или folder при action: "move". Причина — в массиве validation
403 SCOPE_DENIED Ключу не хватает скоупа mail
401 TOKEN_MISSING У API-ключа не настроены токены доступа к почтовому ящику
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Неверный API-ключ
401 KEY_INACTIVE API-ключ неактивен
401 KEY_EXPIRED Срок действия API-ключа истёк
422 BITRIX_ERROR Прочие ошибки Битрикс24
429 RATE_LIMITED Превышен общий лимит запросов платформы
502 BITRIX_UNAVAILABLE Битрикс24 недоступен

Полный список общих ошибок API — Ошибки.

Известные особенности

  • Действия spam и delete необратимы. Пометка как спам и удаление не имеют операции отмены через API.

Смотрите также