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

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

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

422 — нарушена валидация запроса:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Ошибка при валидации объекта запроса"
  }
}

#Ошибки

HTTP Код Описание
422 BITRIX_ERROR Не передан folder при action: "move", значение action не из допустимых, не передан messageIds или операция не выполнена
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-ключа истёк
429 RATE_LIMITED Превышен общий лимит запросов платформы
502 BITRIX_UNAVAILABLE Битрикс24 недоступен

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

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

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

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