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

Forward message

POST /v1/mail/messages/:id/forward

Forwards a message: includes all attachments of the original and quotes its body. Saved to the Sent folder. The message being forwarded is specified in the path.

Parameters

Parameter In Type Required Description
Parameterid Inpath Typeinteger Requiredyes DescriptionIdentifier of the message being forwarded. List: GET /v1/mail/messages

Request fields (body)

Field Type Required Description
Fieldfrom Typestring Requiredyes DescriptionSender address. Allowed values come from GET /v1/mail/mailboxes/:id/senders
Fieldto Typearray of strings Requiredyes DescriptionRecipient addresses
Fieldsubject Typestring Requiredyes DescriptionMessage subject
Fieldbody Typestring Requiredyes DescriptionMessage body
Fieldcc Typearray of strings Requiredno DescriptionCarbon copy addresses
Fieldbcc Typearray of strings Requiredno DescriptionBlind carbon copy addresses

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/1234/forward \
  -d '{
    "from": "sender@example.com",
    "to": ["recipient@example.com"],
    "subject": "Fwd: Message subject",
    "body": "Forwarding the message"
  }'

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/1234/forward \
  -d '{
    "from": "sender@example.com",
    "to": ["recipient@example.com"],
    "subject": "Fwd: Message subject",
    "body": "Forwarding the message"
  }'

JavaScript — personal key

javascript 
const messageId = 1234
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/mail/messages/${messageId}/forward`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      from: 'sender@example.com',
      to: ['recipient@example.com'],
      subject: 'Fwd: Message subject',
      body: 'Forwarding the message',
    }),
  }
)
const data = await res.json()
console.log(data.data.to)

JavaScript — OAuth application

javascript 
const messageId = 1234
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/mail/messages/${messageId}/forward`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      from: 'sender@example.com',
      to: ['recipient@example.com'],
      subject: 'Fwd: Message subject',
      body: 'Forwarding the message',
    }),
  }
)
const data = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue when the request succeeds
Fielddata.success Typeboolean Descriptiontrue when forwarding succeeds
Fielddata.to Typearray of strings DescriptionList of addresses the message was sent to

Response example

JSON 
{
  "success": true,
  "data": {
    "success": true,
    "to": ["recipient@example.com"]
  }
}

Error response example

400 — no recipients passed:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Request object validation failed",
    "validation": [
      {
        "field": "MISSING_TO",
        "message": "Parameter \"to\" is required and must be a non-empty array."
      }
    ]
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionThe id path parameter is not a positive integer
HTTP400 CodeINVALID_PARAMS Descriptionto is missing or the array is empty — validation[].field equals MISSING_TO
HTTP400 CodeINVALID_PARAMS DescriptionThe address in from is not available to the user. Allowed addresses: GET /v1/mail/mailboxes/:id/senders
HTTP400 CodeINVALID_PARAMS DescriptionThe message was deleted or moved to another folder. The reason is in the validation array
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.

See also