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
FieldmessageIds Typearray of integers Requiredyes DescriptionMessage identifiers accessible to the key's user, from the message list. For move, all messages must belong to one mailbox
Fieldaction Typestring Requiredyes DescriptionAction: move — move to a folder, spam — mark as spam, delete — delete
Fieldfolder Typestring Requiredconditional DescriptionTarget 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
Fieldsuccess Typeboolean Descriptiontrue when the request succeeds
Fielddata.success Typeboolean Descriptiontrue when the action succeeds
Fielddata.movedCount Typeinteger DescriptionNumber of processed messages
Fielddata.action Typestring DescriptionPerformed 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
HTTP400 CodeINVALID_PARAMS DescriptionThe action value is not one of the allowed values — validation[].field equals INVALID_ACTION
HTTP400 CodeINVALID_PARAMS DescriptionmessageIds is missing, or folder is missing when action: "move". The reason is in the validation array
HTTP400 CodeINVALID_PARAMS DescriptionmessageIds 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
HTTP400 CodeINVALID_PARAMS DescriptionFor move, accessible messages belong to multiple mailboxes. error.validation[].message contains All messages must belong to the same mailbox.
HTTP400 CodeINVALID_PARAMS DescriptionNo accessible messages were found. error.validation[].message contains No accessible messages found.
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the mail scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no access tokens configured for the mailbox
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP401 CodeKEY_INACTIVE DescriptionThe API key is inactive
HTTP401 CodeKEY_EXPIRED DescriptionThe API key has expired
HTTP422 CodeBITRIX_ERROR DescriptionOther Bitrix24 errors
HTTP429 CodeRATE_LIMITED DescriptionThe platform-wide request limit was exceeded
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 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. Group messages by mailboxId and source folder. 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