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
id path integer yes Identifier of the message being forwarded. List: GET /v1/mail/messages

Request fields (body)

Field Type Required Description
from string yes Sender address. Allowed values come from GET /v1/mail/mailboxes/:id/senders
to array of strings yes Recipient addresses
subject string yes Message subject
body string yes Message body
cc array of strings no Carbon copy addresses
bcc array of strings no Blind 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
success boolean true when the request succeeds
data.success boolean true when forwarding succeeds
data.to array of strings List 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
400 INVALID_PARAMS The id path parameter is not a positive integer
400 INVALID_PARAMS to is missing or the array is empty — validation[].field equals MISSING_TO
400 INVALID_PARAMS The address in from is not available to the user. Allowed addresses: GET /v1/mail/mailboxes/:id/senders
400 INVALID_PARAMS The message was deleted or moved to another folder. The reason is in the validation array
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.

See also