> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Отправка email

> Отправляйте HTML- или текстовые письма и отслеживайте доставку для каждого получателя.

## Что это

Email API отправляет одно письмо одному или нескольким получателям. Используйте его для транзакционных уведомлений, обновлений аккаунта, квитанций и персонализированных сообщений.

## Перед началом

* Сохраните ваш API-ключ YCloud в `YCLOUD_API_KEY`.
* Зарегистрируйте и активируйте домен отправителя в вашем аккаунте YCloud.
* Используйте адрес отправителя с активированного домена.
* Подготовьте HTML- или текстовый контент не более 150 КБ.

## Как это работает

Отправьте письмо запросом `POST /emails`. Ответ подтверждает, что YCloud принял письмо, и возвращает его `id`. Доставка происходит отдельно для каждого адреса в `to`, `cc` и `bcc`.

Подпишитесь на `email.delivery.updated`, чтобы получать состояния на уровне получателей, такие как `sent`, `delivered`, `undelivered` и `failed`.

## Запрос

`POST /emails`

### Поля запроса

| Поле | Обязательное | Описание |
| - | - | - |
| `from` | Да | Адрес отправителя с активированного домена. Отображаемое имя необязательно. |
| `to` | Да | Один или несколько адресов получателей через запятую. Максимум 100 адресов. |
| `subject` | Да | Строка темы. Максимум 255 символов. |
| `content` | Да | HTML- или текстовое тело. Максимальный размер 150 КБ. |
| `contentType` | Нет | `text/html` или `text/plain`. Значения по умолчанию и поведение отслеживания зависят от типа контента. |
| `cc` | Нет | Получатели копии через запятую. |
| `bcc` | Нет | Получатели скрытой копии через запятую. |
| `replyTo` | Нет | Адрес, используемый при ответе получателя. |
| `summary` | Нет | Краткое описание письма. Максимум 70 символов. |
| `variables` | Нет | Один объект персонализации для каждого адреса в `to`. |
| `externalId` | Нет | Ваша уникальная ссылка для сверки письма с внутренней записью. |
| `callbackUrl` | Нет | URL отчёта о доставке для конкретного сообщения. Для новых интеграций используйте эндпоинты вебхуков. |

### Пример запроса

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST https://api.ycloud.com/v2/emails \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "Support Team<support@example.com>",
    "to": "customer@example.com",
    "subject": "Welcome",
    "contentType": "text/html",
    "content": "<h1>Welcome</h1><p>Thanks for joining us.</p>",
    "externalId": "welcome-10001"
  }'
```

## Ответ

Успешный ответ возвращает созданный объект email. Приём не означает, что каждый получатель получил письмо.

### Пример ответа

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "EMAIL_ID",
  "from": {
    "address": "support@example.com",
    "name": "Support Team"
  },
  "to": [
    {
      "address": "customer@example.com"
    }
  ],
  "subject": "Welcome",
  "contentType": "text/html",
  "externalId": "welcome-10001",
  "totalRecipients": 1,
  "createTime": "2026-07-16T12:00:00.000Z"
}
```

### Поля ответа

| Поле | Описание |
| - | - |
| `id` | ID письма в YCloud. Сохраните его, чтобы связывать события доставки получателей. |
| `from` | Разобранный ящик отправителя. |
| `to`, `cc`, `bcc` | Разобранные ящики получателей. |
| `contentType` | MIME-тип, используемый для тела письма. |
| `totalRecipients` | Общее число получателей по `to`, `cc` и `bcc`. |
| `totalPrice` | Общая стоимость письма, если доступно. |
| `currency` | Валюта цены по ISO 4217. |
| `createTime` | Время создания письма в формате RFC 3339. |
| `externalId` | Ссылка, указанная в запросе. |

## Персонализация контента

Размещайте переменные между символами `#` в контенте. Указывайте один объект переменных для каждого адреса в `to`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "to": "alice@example.com,bob@example.com",
  "content": "Hello #name#!",
  "variables": [
    { "name": "Alice" },
    { "name": "Bob" }
  ]
}
```

## Статус доставки

Подпишитесь на `email.delivery.updated`. Каждое событие идентифицирует письмо и конкретный `recipientAddress`, так как получатели могут иметь разные финальные состояния.

Сообщения `text/plain` не генерируют события отслеживания кликов или открытий.

## Ограничения и устранение неполадок

* Домен отправителя должен быть активирован до отправки.
* `to` поддерживает не более 100 адресов.
* `subject` поддерживает не более 255 символов.
* `content` поддерживает не более 150 КБ.
* После успешного ответа API у получателя всё ещё может произойти событие `undelivered` или `failed`.
* При расследовании доставки используйте `id` письма, адрес получателя и `externalId`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.