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
Parameterid Inpath Typeinteger Requiredyes DescriptionIdentifier of the message the event is created from. List: GET /v1/mail/messages

Request body fields

Field Type Required Description
FielddateFrom Typestring Requiredyes DescriptionEvent start date and time, format YYYY-MM-DD HH:MM:SS
FielddateTo Typestring Requiredyes DescriptionEvent end date and time, format YYYY-MM-DD HH:MM:SS
Fieldname Typestring Requiredno DescriptionEvent name. Defaults to the message subject
Fielddescription Typestring Requiredno DescriptionEvent 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
Fieldsuccess Typeboolean Descriptiontrue on successful creation
Fielddata.success Typeboolean DescriptionInternal operation success flag
Fielddata.eventId Typeinteger DescriptionIdentifier of the created event
Fielddata.messageId Typeinteger DescriptionIdentifier 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
HTTP400 CodeINVALID_PARAMS DescriptionNon-numeric or negative :id in the path — message id must be a positive integer
HTTP400 CodeINVALID_PARAMS DescriptiondateFrom or dateTo is missing — validation[].field equals MISSING_DATEFROM or MISSING_DATETO
HTTP400 CodeINVALID_PARAMS DescriptionThe 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
HTTP400 CodeINVALID_PARAMS DescriptionThe message was deleted or moved to another folder. The reason is in the validation array
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 DescriptionKey is deactivated
HTTP401 CodeKEY_EXPIRED DescriptionKey has expired
HTTP401 CodeTOKEN_MISSING DescriptionThe key is not linked to a Bitrix24 portal
HTTP403 CodeSCOPE_DENIED DescriptionKey lacks the mail scope
HTTP422 CodeBITRIX_ERROR DescriptionOther Bitrix24 errors
HTTP429 CodeRATE_LIMITED DescriptionRequest limit exceeded
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable

Full list of common API errors — Errors.

See also