# Mail

Bitrix24 account mail: receiving and sending messages, managing mailboxes, and converting incoming messages into tasks, events, chats, and posts.

**Scope:** `mail` · **Base URL:** `https://vibecode.bitrix24.com/v1` · **Authorization:** `X-Api-Key` header

## Documentation sections

- [Mailboxes](/docs/mail/mailboxes) — list, get, senders (3 endpoints)
- [Messages](/docs/mail/messages) — list, read, thread, send, reply, forward, move (7 endpoints)
- [Creating objects from a message](/docs/mail/conversions) — task, event, chat, post, CRM binding and its deletion (6 endpoints)
- [Recipients](/docs/mail/recipients) — search contacts and employees (2 endpoints)

## Quick start

Two calls to confirm the API works: get the list of mailboxes and the first messages.

### curl

```bash
# List of mailboxes
curl "https://vibecode.bitrix24.com/v1/mail/mailboxes" \
  -H "X-Api-Key: YOUR_API_KEY"

# Messages in the specified mailbox
curl "https://vibecode.bitrix24.com/v1/mail/messages?mailboxId=5" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### JavaScript

```javascript
const BASE = 'https://vibecode.bitrix24.com/v1'
const headers = { 'X-Api-Key': 'YOUR_API_KEY' }

const mbRes = await fetch(`${BASE}/mail/mailboxes`, { headers })
const { data: mailboxes } = await mbRes.json()
const mailboxId = mailboxes[0].id

const msgsRes = await fetch(`${BASE}/mail/messages?mailboxId=${mailboxId}`, { headers })
const { data } = await msgsRes.json()
console.log(`Messages in mailbox: ${data.items.length}`)
```

## Full example

A JavaScript scenario — seven steps: get the list of mailboxes, find the sender address, send a message, read it, reply, and create a task.

```javascript
const BASE = 'https://vibecode.bitrix24.com/v1'
const HEADERS = { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }

async function api(method, path, body = null) {
  const opts = { method, headers: HEADERS }
  if (body) opts.body = JSON.stringify(body)
  return (await fetch(`${BASE}${path}`, opts)).json()
}

// 1. List of mailboxes → mailboxId
const { data: mailboxes } = await api('GET', '/mail/mailboxes')
const mailboxId = mailboxes[0].id

// 2. Mailbox sender addresses → from string
const { data: sendersData } = await api('GET', `/mail/mailboxes/${mailboxId}/senders`)
const from = sendersData.items[0].sender  // "Name <user@example.com>"

// 3. Send a message
const sendRes = await api('POST', '/mail/messages', {
  from,
  to: ['colleague@example.com'],
  subject: 'Integration request',
  body: 'Hello, please clarify the details.',
})
// → { success: true, data: { success: true, to: ["colleague@example.com"] } }
console.log('Sent:', sendRes.data.to)

// 4. Find the message in the mailbox → id
const { data: msgsData } = await api('GET', `/mail/messages?mailboxId=${mailboxId}&limit=5`)
const messageId = msgsData.items[0].id

// 5. Get the full message text (data.item field)
const { data: msgData } = await api('GET', `/mail/messages/${messageId}`)
console.log('Subject:', msgData.item.subject, '| Body:', msgData.item.body)

// 6. Reply to the message — the message is specified in the path
const replyRes = await api('POST', `/mail/messages/${messageId}/reply`, {
  from,
  to: ['colleague@example.com'],
  subject: `Re: ${msgData.item.subject}`,
  body: 'Thanks, clarification received.',
})
// → { success: true, data: { success: true, to: ["colleague@example.com"] } }
console.log('Reply sent:', replyRes.data.to)

// 7. Create a task from the message
const taskRes = await api('POST', `/mail/messages/${messageId}/task`, {
  title: 'Process the incoming request',
})
// → { success: true, data: { success: true, taskId: 100, messageId: 1000 } }
console.log('Task created, id:', taskRes.data.taskId)
```

## Endpoint reference

**Mailboxes:**

| Method | Path | Bitrix24 method | Description |
|-------|------|----------------|----------|
| GET | [`/v1/mail/mailboxes`](/docs/mail/mailboxes/list) | mail.mailbox.list | List of mailboxes |
| GET | [`/v1/mail/mailboxes/:id`](/docs/mail/mailboxes/get) | mail.mailbox.get | Get a mailbox |
| GET | [`/v1/mail/mailboxes/:id/senders`](/docs/mail/mailboxes/senders) | mail.mailbox.senders | Mailbox sender addresses |

**Messages:**

| Method | Path | Bitrix24 method | Description |
|-------|------|----------------|----------|
| GET | [`/v1/mail/messages`](/docs/mail/messages/list) | mail.message.list | List of messages |
| GET | [`/v1/mail/messages/:id`](/docs/mail/messages/get) | mail.message.get | Get a message |
| GET | [`/v1/mail/messages/:id/thread`](/docs/mail/messages/thread) | mail.message.thread | Conversation thread |
| POST | [`/v1/mail/messages`](/docs/mail/messages/send) | mail.message.send | Send a message |
| POST | [`/v1/mail/messages/:id/reply`](/docs/mail/messages/reply) | mail.message.reply | Reply to a message |
| POST | [`/v1/mail/messages/:id/forward`](/docs/mail/messages/forward) | mail.message.forward | Forward a message |
| POST | [`/v1/mail/messages/move`](/docs/mail/messages/move) | mail.message.movetofolder | Move messages |

**Creating objects from a message:**

| Method | Path | Bitrix24 method | Description |
|-------|------|----------------|----------|
| POST | [`/v1/mail/messages/:id/task`](/docs/mail/conversions/task) | mail.message.createtask | Create a task from a message |
| POST | [`/v1/mail/messages/:id/calendar-event`](/docs/mail/conversions/calendar-event) | mail.message.createcalendarevent | Create an event from a message |
| POST | [`/v1/mail/messages/:id/chat`](/docs/mail/conversions/chat) | mail.message.createchat | Create a chat from a message |
| POST | [`/v1/mail/messages/:id/feed-post`](/docs/mail/conversions/feed-post) | mail.message.createfeedpost | Create a Feed post |
| POST | [`/v1/mail/messages/:id/crm-activity`](/docs/mail/conversions/crm-activity-create) | mail.message.createcrmactivity | Bind a message to CRM |
| DELETE | [`/v1/mail/messages/:id/crm-activity`](/docs/mail/conversions/crm-activity-delete) | mail.message.removecrmactivity | Delete a CRM activity from a message |

**Recipients:**

| Method | Path | Bitrix24 method | Description |
|-------|------|----------------|----------|
| POST | [`/v1/mail/recipients/contacts`](/docs/mail/recipients/contacts) | mail.recipient.listcontacts | Search CRM contacts |
| POST | [`/v1/mail/recipients/employees`](/docs/mail/recipients/employees) | mail.recipient.listemployees | Search Bitrix24 account employees |

## Error codes

### Mail errors

| Code | HTTP | Description |
|-----|------|----------|
| `SCOPE_DENIED` | 403 | The key has no `mail` scope |
| `TOKEN_MISSING` | 401 | The key has no Bitrix24 tokens configured |
| `INVALID_PARAMS` | 400 | `:id` or `:mailboxId` is not a positive integer |
| `INVALID_PARAMS` | 400 | Bitrix24 rejected the request parameters during validation |
| `NOT_FOUND` | 404 | Unknown action (action endpoints only) |
| `ENTITY_NOT_FOUND` | 404 | Message or mailbox not found in Bitrix24 |
| `BITRIX_ACCESS_DENIED` | 403 | No permission to access the mailbox or message in Bitrix24 |
| `RATE_LIMITED` | 429 | Request limit exceeded (header `Retry-After: 2`) |
| `BITRIX_UNAVAILABLE` | 502 | Bitrix24 returned a 5xx error |
| `BITRIX_ERROR` | 422 | Other Bitrix24 errors |

### System errors

| Code | HTTP | Description |
|-----|------|----------|
| `MISSING_API_KEY` | 401 | The `X-Api-Key` header was not provided |
| `INVALID_API_KEY` | 401 | Invalid or expired API key |
| `KEY_INACTIVE` | 401 | The key is deactivated |
| `KEY_EXPIRED` | 401 | The key has expired |

Full list of common API errors — [Errors](/docs/errors).

## See also

- [Keys and authorization](/docs/keys-auth)
- [Entity API conventions](/docs/entity-api)
- [Errors](/docs/errors)