## Create a task from a message

`POST /v1/mail/messages/:id/task`

Creates a task from a message. The message identifier is taken from the path. The request body sets only the task fields and may be empty.

## Parameters

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

## Request body fields

| Field | Type | Required | Description |
|------|-----|:-----:|----------|
| `title` | string | no | Task title. Defaults to the message subject |
| `responsibleId` | integer | no | Identifier of the responsible person. List: `GET /v1/users`. Defaults to the current user |
| `description` | string | no | Task description |

## Examples

### curl — personal key

```bash
curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Process the client request"}' \
  https://vibecode.bitrix24.com/v1/mail/messages/123/task
```

### curl — OAuth application

```bash
curl -X POST \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Process the client request"}' \
  https://vibecode.bitrix24.com/v1/mail/messages/123/task
```

### JavaScript — personal key

```javascript
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/mail/messages/123/task',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ title: 'Process the client request' }),
  }
)
const body = await res.json()
if (!body.success) throw new Error(body.error.code)
console.log(`Task created: ${body.data.taskId}`)
```

### JavaScript — OAuth application

```javascript
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/mail/messages/123/task',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ title: 'Process the client request' }),
  }
)
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` on successful creation |
| `data.success` | boolean | Internal operation success flag |
| `data.taskId` | integer | Identifier of the created task |
| `data.messageId` | integer | Identifier of the message the task was created from |

## Response example

```json
{
  "success": true,
  "data": {
    "success": true,
    "taskId": 4567,
    "messageId": 123
  }
}
```

## Error response example

400 — message not found:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Request object validation failed",
    "validation": [
      {
        "message": "The message was deleted or moved to another folder"
      }
    ]
  }
}
```

## 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` | 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` | 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](/docs/errors).

## Known specifics

- The task is populated with only the title, responsible person, description, and the link to the message. If the Bitrix24 account has required task user fields configured, creation fails with an error.

## See also

- [Create an event from a message](./calendar-event.md)
- [Create a chat from a message](./chat.md)
- [Create objects from a message](/docs/mail/conversions)
- [Mail](/docs/mail)
- [Errors](/docs/errors)