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

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

POST /v1/mail/messages/move

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

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

Поле Тип Обяз. Описание
messageIds array of integers да Идентификаторы писем, доступных пользователю ключа, из списка писем. Для move все письма должны принадлежать одному почтовому ящику
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
400 INVALID_PARAMS В messageIds попали письма из разных папок — validation[].field равен MAIL_CLIENT_MESSAGES_MULTIPLE_FOLDERS, текст от Битрикс24: «Выберите письма из одной папки». Ни одно письмо при этом не обработано
400 INVALID_PARAMS Для move доступны письма из нескольких ящиков. В error.validation[].message приходит All messages must belong to the same mailbox.
400 INVALID_PARAMS Не найдено ни одного доступного письма. В error.validation[].message приходит No accessible messages found.
403 SCOPE_DENIED Ключу не хватает скоупа mail
401 TOKEN_MISSING У API-ключа не настроены токены доступа к почтовому ящику
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Ключ не опознан: такой строки на платформе нет
401 KEY_INACTIVE API-ключ неактивен
401 KEY_EXPIRED Срок действия API-ключа истёк
422 BITRIX_ERROR Прочие ошибки Битрикс24
429 RATE_LIMITED Превышен общий лимит запросов платформы
502 BITRIX_UNAVAILABLE Битрикс24 недоступен

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

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

  • Все письма вызова должны лежать в одной папке. Массив messageIds из разных папок отклоняется целиком — ни одно письмо не обрабатывается. Группируйте письма по mailboxId и исходной папке. Отбирайте письма по папке параметром folder в списке писем и вызывайте перемещение отдельно для каждой папки.
  • Действия spam и delete необратимы через API. Удаление переносит письма в корзину, откуда их можно вернуть в интерфейсе Битрикс24, но операции отмены у самого метода нет.

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