## Invite guests by email

`POST /v1/chats/:dialogId/guest-invites/email`

Sends chat invitations by email to people outside the Bitrix24 account: a personal guest link is created for each address, and Bitrix24 sends it in an email. Up to 10 invitations per call.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `dialogId` (path) | string | yes | Dialog ID: `chatXXX` for a group chat, a numeric user ID for a private chat, `me` — your personal dialog. List — [`GET /v1/chats/recent`](/docs/chats/discovery/recent) |

## Request fields (body)

| Field | Type | Required | Description |
|------|-----|:-----:|---------|
| `invitations` | array | yes | Invitations, from 1 to 10 items |
| `invitations[].email` | string | yes | The guest's email address, up to 254 characters |
| `invitations[].name` | string \| null | no | The guest's name for the invitation text, up to 255 characters |

Other body and item fields, as well as query parameters, are rejected with `400 INVALID_PARAMS`.

## Examples

### curl — personal key

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/chats/chat42/guest-invites/email" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invitations": [{"email": "guest@example.invalid", "name": "Alex"}]}'
```

### curl — OAuth application

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/chats/chat42/guest-invites/email" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"invitations": [{"email": "guest@example.invalid", "name": "Alex"}]}'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat42/guest-invites/email', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ invitations: [{ email: 'guest@example.invalid', name: 'Alex' }] }),
})

const { data } = await res.json()
for (const item of data) {
  console.log(item.email, item.error ? `not sent: ${item.error.code}` : 'sent')
}
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat42/guest-invites/email', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ invitations: [{ email: 'guest@example.invalid', name: 'Alex' }] }),
})

const { data } = await res.json()
for (const item of data) {
  console.log(item.email, item.error ? `not sent: ${item.error.code}` : 'sent')
}
```

## Response fields

`data` is an array with one item per invitation, in request order. An item is either a sent invitation or a refusal for it.

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | `true` even if some invitations were not sent — check each invitation's outcome in its item |
| `data[].email` | string | The address from the request |
| `data[].sharingLink` | object | Sent invitations only. The personal guest link: `entityType` — `guest_chat`, `type` — `custom`, `name` — the email address, `url` — the link URL for the guest, `dateExpire` — one day after creation |
| `data[].error.code` | string | Refusals only. The refusal code — see "Per-item refusals" below |
| `data[].error.message` | string | Refusals only. The refusal text |

### Per-item refusals

| Code | When |
|-----|-------|
| `GUEST_INVITE_INVALID_EMAIL` | The address is invalid |
| `GUEST_INVITE_COOLDOWN` | This address was already invited to this chat within the last 5 minutes |
| `GUEST_INVITE_AUTHOR_RATE_LIMIT` | You have created 10 guest links within the last hour — across all chats, including invitations and revoked links |
| `GUEST_INVITE_EMAIL_SEND_FAILED` | The email was not sent, and the link was deleted |

## Response example

The first invitation is sent, the second is refused:

```json
{
  "success": true,
  "data": [
    {
      "sharingLink": {
        "id": 1016,
        "entityId": "42",
        "entityType": "guest_chat",
        "code": "Wd3nTf8cLq2yHs6J",
        "type": "custom",
        "dateCreate": "2026-09-24T23:07:52+00:00",
        "dateExpire": "2026-09-25T23:07:52+00:00",
        "requireApproval": false,
        "url": "https://b24.to/gi/a1b2c3d4e5-Wd3nTf8cLq2yHs6J?IM_DIALOG=chat42&name=Alex",
        "name": "guest@example.invalid"
      },
      "email": "guest@example.invalid"
    },
    {
      "email": "not-an-address@",
      "error": {
        "code": "GUEST_INVITE_INVALID_EMAIL",
        "message": "GUEST_INVITE_INVALID_EMAIL"
      }
    }
  ]
}
```

## Error response example

400 — an item field is not accepted:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`invitations[0].phone` is not accepted. Accepted: email, name."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | The body is not an object or carries a field other than `invitations`; `invitations` is missing or does not hold from 1 to 10 items; an item is not an object or carries a field other than `email` and `name`; `email` is empty or longer than 254 characters; `name` is neither a string of up to 255 characters nor `null`; a query parameter was passed. The message names the item index and the field and does not repeat the value. Checked before any call to Bitrix24 |
| 422 | `BITRIX_ERROR` | Bitrix24 returned an error; the portal code is in `error.b24Code`. `CHAT_NOT_FOUND` — the chat does not exist on the portal |
| 404 | `ENTITY_NOT_FOUND` | Bitrix24 answered with an unspecified "not found" code; the portal code is in `error.b24Code` |
| 502 | `ME_ALIAS_RESOLUTION_FAILED` | Failed to resolve the user for the `me` alias |
| 403 | `BITRIX_ACCESS_DENIED` | No right to invite guests to this chat — Bitrix24 refused with the `ACCESS_DENIED` code |
| 403 | `SCOPE_DENIED` | The API key does not have the `im` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only — see [access rights](/docs/access-rights) |
| 401 | `TOKEN_MISSING` | The API key has no Bitrix24 tokens configured |

The full list of general API errors — [Errors](/docs/errors).

## Known specifics

**Automatic chat membership.** The call can make the key owner a member of a chat that allows auto-join, even if the link operation is subsequently refused. A read-only key is blocked before Bitrix24 is called.

**A retry after a dropped connection does not send the email twice.** Re-inviting the same address to the same chat within 5 minutes is refused with `GUEST_INVITE_COOLDOWN` instead of sending a second email.

**All chat members will see the address.** Every invitation sent leaves a system message with the guest's address in the chat. Vibecode does not store the invitation body in its logs.

**An invitation cannot be revoked.** Neither [guest link revocation](/docs/chats/sharing/guest-link-revoke) nor [revoking by code](/docs/chats/sharing/link-revoke) removes a personal invitation. The invitation remains valid until its `dateExpire`.

## See also

- [Invite guests by SMS](/docs/chats/sharing/invite-phone)
- [Get a guest link](/docs/chats/sharing/guest-link)
- [Get a link by code](/docs/chats/sharing/link-get)
- [Links and guests](/docs/chats/sharing)