For AI agents: markdown of this page — /docs-content-en/mail/messages/move.md documentation index — /llms.txt

Move messages

POST /v1/mail/messages/move

Performs a bulk action on messages: moves them to a folder, marks them as spam, or deletes them.

Request fields (body)

Field Type Required Description
messageIds array of integers yes Message identifiers
action string yes Action: move — move to a folder, spam — mark as spam, delete — delete
folder string conditional Target folder. Required when action: "move"

Examples

curl — personal key

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

curl — OAuth application

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.com/v1/mail/messages/move \
  -d '{
    "messageIds": [1234],
    "action": "move",
    "folder": "INBOX"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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 application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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()

Response fields

Field Type Description
success boolean true when the request succeeds
data.success boolean true when the action succeeds
data.movedCount integer Number of processed messages
data.action string Performed action (move, spam or delete)

Response example

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

Error response example

400 — the action value is not allowed:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Request object validation failed",
    "validation": [
      {
        "field": "INVALID_ACTION",
        "message": "Parameter \"action\" must be \"move\", \"spam\", or \"delete\"."
      }
    ]
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS The action value is not one of the allowed values — validation[].field equals INVALID_ACTION
400 INVALID_PARAMS messageIds is missing, or folder is missing when action: "move". The reason is in the validation array
400 INVALID_PARAMS messageIds mixes messages from different folders — validation[].field equals MAIL_CLIENT_MESSAGES_MULTIPLE_FOLDERS, and the message text comes from Bitrix24. No message is processed in that case
403 SCOPE_DENIED The key lacks the mail scope
401 TOKEN_MISSING The API key has no access tokens configured for the mailbox
401 MISSING_API_KEY The X-Api-Key header is missing
401 INVALID_API_KEY Invalid API key
401 KEY_INACTIVE The API key is inactive
401 KEY_EXPIRED The API key has expired
422 BITRIX_ERROR Other Bitrix24 errors
429 RATE_LIMITED The platform-wide request limit was exceeded
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable

Full list of common API errors — Errors.

Known specifics

  • Every message in a call must sit in the same folder. A messageIds array mixing folders is rejected whole — no message is processed. Select messages by folder with the folder parameter of the message list and call the move once per folder.
  • The spam and delete actions cannot be undone through the API. Deleting moves messages to the trash folder, where they can be restored from the Bitrix24 interface, but the method itself has no undo.

See also