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

Create an event from a message

POST /v1/mail/messages/:id/calendar-event

Creates a calendar event from a message. The message identifier is taken from the path. The request body sets the event fields.

Parameters

Parameter In Type Required Description
id path integer yes Identifier of the message the event is created from. List: GET /v1/mail/messages

Request body fields

Field Type Required Description
dateFrom string yes Event start date and time, format YYYY-MM-DD HH:MM:SS
dateTo string yes Event end date and time, format YYYY-MM-DD HH:MM:SS
name string no Event name. Defaults to the message subject
description string no Event description

Examples

curl — personal key

Terminal 
curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dateFrom": "2026-06-01 10:00:00", "dateTo": "2026-06-01 11:00:00", "name": "Meeting about the request"}' \
  https://vibecode.bitrix24.com/v1/mail/messages/123/calendar-event

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" \
  -d '{"dateFrom": "2026-06-01 10:00:00", "dateTo": "2026-06-01 11:00:00", "name": "Meeting about the request"}' \
  https://vibecode.bitrix24.com/v1/mail/messages/123/calendar-event

JavaScript — personal key

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/mail/messages/123/calendar-event',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      dateFrom: '2026-06-01 10:00:00',
      dateTo: '2026-06-01 11:00:00',
      name: 'Meeting about the request',
    }),
  }
)
const body = await res.json()
if (!body.success) throw new Error(body.error.code)
console.log(`Event created: ${body.data.eventId}`)

JavaScript — OAuth application

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/mail/messages/123/calendar-event',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      dateFrom: '2026-06-01 10:00:00',
      dateTo: '2026-06-01 11:00:00',
      name: 'Meeting about the request',
    }),
  }
)

Response fields

Field Type Description
success boolean true on successful creation
data.success boolean Internal operation success flag
data.eventId integer Identifier of the created event
data.messageId integer Identifier of the message the event was created from

Response example

JSON 
{
  "success": true,
  "data": {
    "success": true,
    "eventId": 712,
    "messageId": 123
  }
}

Error response example

400 — the start date is missing:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Request object validation failed",
    "validation": [
      {
        "field": "MISSING_DATEFROM",
        "message": "Parameter \"dateFrom\" is required."
      }
    ]
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS Non-numeric or negative :id in the path — message id must be a positive integer
400 INVALID_PARAMS dateFrom or dateTo is missing — validation[].field equals MISSING_DATEFROM or MISSING_DATETO
400 INVALID_PARAMS The dateFrom or dateTo value is not in the YYYY-MM-DD HH:MM:SS format. The message in the validation array names the rejected value
400 INVALID_PARAMS The message was deleted or moved to another folder. The reason is in the validation array
401 MISSING_API_KEY The X-Api-Key header is missing
401 INVALID_API_KEY Invalid or expired key
401 KEY_INACTIVE Key is deactivated
401 KEY_EXPIRED Key has expired
401 TOKEN_MISSING The key is not linked to a Bitrix24 portal
403 SCOPE_DENIED Key lacks the mail scope
422 BITRIX_ERROR Other Bitrix24 errors
429 RATE_LIMITED Request limit exceeded
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable

Full list of common API errors — Errors.

See also