[Документация Yandex Cloud](../../../index.md) > [Yandex Cloud Postbox](../../index.md) > [Справочник API](../index.md) > [REST](index.md) > Отправка писем

# Метод SendEmail

Отправляет электронное письмо с [адреса](../../concepts/glossary.md#adress) в каталоге. Нужный каталог определяется по сервисному аккаунту, от имени которого выполняется запрос.

Альтернативный способ отправки почты — с помощью [протокола SMTP](../../quickstart.md#smtp).

## Запрос {#request}

```http
POST /v2/email/outbound-emails HTTP/2
```

### Заголовки запроса {#request-headers}

Используйте в запросе [общие заголовки](request-headers.md).

### Тело запроса {#request-body}

```json
{
  "ConfigurationSetName": "string",
  "FromEmailAddress": "<адрес_отправителя>",
  "FromEmailAddressIdentityArn": "<параметр_для_совместимости>",
  "Destination": {
    "ToAddresses": [
      "<адрес_получателя>"
    ],
    "CcAddresses": [
      "<адрес_получателя_копии>"
    ],
    "BccAddresses": [
      "<адрес_получателя_скрытой_копии>"
    ]
  },
  "Content": {
    "Simple": {
      "Subject": {
        "Data": "<текст_темы>",
        "Charset": "<кодировка>"
      },
      "Headers": [
        {
          "Name": "<заголовок>",
          "Value": "<значение>"
        }
      ],
      "Body": {
        "Text": {
          "Data": "<текст_письма>",
          "Charset": "<кодировка>"
        },
        "Html": {
          "Data": "<текст_письма>",
          "Charset": "<кодировка>"
        }
      },
      "Attachments": [
        {
          "FileName": "<имя_файла>",
          "RawContent": "<содержимое_в_Base64>",
          "ContentType": "<MIME-тип>",
          "ContentDescription": "<описание_вложения>",
          "ContentDisposition": "<способ_отображения>",
          "ContentId": "<идентификатор_вложения>",
          "ContentTransferEncoding": "base64"
        }
      ]
    },
    "Template": {
      "Headers": [
        {
          "Name": "<заголовок>",
          "Value": "<значение>"
        }
      ],
      "TemplateContent": {
        "Html": "<шаблон_HTML>",
        "Subject": "<шаблон_темы>",
        "Text": "<шаблон_текста>"
      },
      "TemplateData": "<данные_для_подстановки_в_шаблоны>",
      "Attachments": [
        {
          "FileName": "<имя_файла>",
          "RawContent": "<содержимое_в_Base64>",
          "ContentType": "<MIME-тип>",
          "ContentDescription": "<описание_вложения>",
          "ContentDisposition": "<способ_отображения>",
          "ContentId": "<идентификатор_вложения>",
          "ContentTransferEncoding": "base64"
        }
      ]
    },
    "Raw": {
      "Data": "<все_содержимое_письма>"
    }
  },
  "ListManagementOptions": {
    "ContactListName": "<имя_списка_контактов>",
    "TopicName": "<имя_темы>"
  }
}
```

#|
|| **Параметр** | **Описание** ||
|| `ConfigurationSetName` | **Тип**: string.

Имя конфигурации, которая используется для отправки письма. Если не указано, используется конфигурация, привязанная к адресу Yandex Cloud Postbox. ||
|| `FromEmailAddress` | **Тип**: string.

Адрес, с которого отправляется письмо. Он должен быть верифицирован. ||
|| `FromEmailAddressIdentityArn` | **Тип**: string.

Параметр не используется. Предназначен для совместимости с AWS. ||
|| `Destination` | **Тип**: object.

Объект, который содержит адреса для доставки письма.

* `ToAddresses` — адреса, на которые отправляется письмо. Тип: array.
* `CcAddresses` — адреса, на которые отправляется копия письма. Тип: array.
* `BccAddresses` — адреса, на которые отправляется скрытая копия письма. Тип: array. ||

|| `ListManagementOptions` | **Тип**: object.

Параметры для управления [механизмом отписки от рассылок](../../concepts/unsubscribe.md).

* `ContactListName` — имя списка контактов. Тип: string. Обязательный параметр.
* `TopicName` — имя темы внутри списка контактов. Тип: string. Необязательный параметр. ||
|| `Simple` | **Тип**: object.

Простой тип. Нельзя использовать вместе с `Raw` или `Template`. Подходит, если нужно отправить письмо без дополнительных настроек. Такое письмо состоит из темы и содержимого. Тип: object. ||
|| `Subject` | **Тип**: object.

Описывает тему:

* `Data` — текст темы. Тип: string.
* `Charset` — кодировка. Тип: string. Возможные значения: `UTF-8`. ||
|| `Headers` | **Тип**: array.
* `Name` — имя заголовка. Тип: string.
* `Value` — значение заголовка. Тип: string.

`Name` не может быть одним из ограниченных заголовков: `BCC`, `CC`, `Content-Disposition`, `Content-Type`, `Date`,
`From`, `Message-ID`, `MIME-Version`, `Reply-To`, `Return-Path`, `Subject`, `To`.||
|| `Body` | **Тип**: object.

Описывает содержимое:

* `Text` — объект, отвечающий за отображение письма в почтовых клиентах, которые не поддерживают HTML. Тип: object.
  * `Data` — текст письма. Тип: string.
  * `Charset` — кодировка. Тип: string. Возможные значения: `UTF-8`.
* `Html` — объект, отвечающий за отображение письма в почтовых клиентах, которые поддерживают HTML. Тип: object.
  * `Data` — текст письма. Тип: string.
  * `Charset` — кодировка. Тип: string. Возможные значения: `UTF-8`. ||
|| `Attachments` | **Тип**: array.

Список вложений в письме. Доступен в содержимом типов `Simple` и `Template`. Каждое вложение описывается объектом со следующими полями:

* `FileName` — имя файла вложения. Тип: string. Обязательное поле. Не должно содержать символы `/` и `\`. Расширение файла не должно входить в [список запрещенных](../../concepts/restrictions.md).
* `RawContent` — содержимое файла, закодированное в Base64. Тип: string (byte). Обязательное поле. Не должно быть пустым.
* `ContentType` — MIME-тип содержимого (например, `application/pdf`). Тип: string. Необязательное поле. Если не указан, определяется по расширению файла. Если определить тип не удалось, используется `application/octet-stream`.
* `ContentDescription` — описание вложения, передается в MIME-заголовке `Content-Description`. Тип: string. Необязательное поле.
* `ContentDisposition` — способ отображения вложения. Тип: string. Необязательное поле. Значения указываются без учета регистра:
  * `ATTACHMENT` — вложение передается как отдельный файл. Значение по умолчанию.
  * `INLINE` — вложение встраивается в тело письма (например, изображение в HTML). Письмо должно содержать HTML-тело.
* `ContentId` — идентификатор вложения, на который можно ссылаться из HTML с помощью схемы `cid:`. Тип: string. Обязательное поле для вложений с `ContentDisposition`: `INLINE`. Должен быть уникальным в пределах письма.
* `ContentTransferEncoding` — способ кодирования содержимого. Тип: string. Необязательное поле. Поддерживается только значение `base64` (без учета регистра).

Подробнее об ограничениях на вложения в разделе [Ограничения на вложения в письмах](../../concepts/restrictions.md). ||
|| `Template` | **Тип**: object.

Шаблонный тип. Нельзя использовать вместе с `Simple` или `Raw`. Подходит, если нужно отправить письмо на основе шаблона. Поддерживаются только шаблоны, передаваемые в запросе.||
|| `TemplateContent` | **Тип**: object.

Содержит шаблон письма:

* `Html` — шаблон HTML. Тип: string.
* `Subject` — шаблон темы. Тип: string.
* `Text` — шаблон текста. Тип: string. ||
|| `TemplateData` | **Тип**: string.

Данные, которые используются для заполнения шаблона. JSON-объект, сериализованный в строку. ||
|| `Raw` | **Тип**: object.

Необработанный тип. Нельзя использовать вместе с `Simple` или `Template`. Подходит, если нужно дополнительно настроить содержимое письма. К такому типу предъявляются требования:

* Письмо должно состоять из заголовка и содержимого, разделенных пустой строкой.
* В письме должны присутствовать все обязательные поля заголовков.
* Все фрагменты MIME-письма должны быть корректно отформатированы.
* Вложения должны быть в формате, который поддерживается сервисом Yandex Cloud Postbox.
* В письме должна использоваться кодировка Base64.
* Если в письме есть содержимое, которое выходит за пределы семиразрядного диапазона символов ASCII, его нужно закодировать, чтобы оно корректно отображалось в почтовом клиенте получателя.
* Максимальная длина строки в письме — 1000 символов.

Письмо целиком размещается в параметре `Data`. Тип: string. ||
|#

## Ответы {#responses}

### 200 OK {#200}

```json
{
  "MessageId": "<идентификатор_письма>"
}
```

#|
|| **Параметр** | **Описание** ||
|| `MessageId` | **Тип**: string.

Уникальный идентификатор письма. ||
|#

### Ошибки {#errors}

Для всех ошибок тело ответа представлено в одинаковом формате:

```json
{
   "Code": "<название_ошибки>",
   "message": "<пояснение_к_ошибке>"
}
```

Название ошибки заимствуется из ее кода, например `BadRequestException`.

Возможные ошибки:

#|
|| **Код ошибки** | **Описание** ||
|| `400 BadRequestException` | В запросе неправильно указаны заголовки или параметры. ||
|| `400 BadRequestException: sender is not allowed` | [Отправитель](../../concepts/glossary.md#sender) не входит в список разрешенных отправителей, которые указаны в настройках адреса. ||
|| `400 AccountSuspendedException` | Возможность отправлять почту для сервисного аккаунта, от имени которого выполняется запрос, навсегда ограничена. ||
|| `400 SendingPausedException` | Возможность отправлять почту для сервисного аккаунта, от имени которого выполняется запрос, временно ограничена. ||
|| `400 MessageRejected` | Письмо содержит некорректные данные. ||
|| `400 MailFromDomainNotVerifiedException` | Адрес, с которого отправляется письмо, не верифицирован. ||
|| `404 NotFoundException` | Запрошенный ресурс не найден. ||
|| `429 TooManyRequestsException` | При вызове запроса превышена [квота](../../concepts/limits.md#postbox-quotas). ||
|| `400 LimitExceededException` | При вызове запроса превышен [лимит](../../concepts/limits.md). ||
|#

## Полезные ссылки {#see-also}

* [Как пользоваться API Amazon для работы с Yandex Cloud Postbox](../index.md)
* [Аутентификация в API Yandex Cloud Postbox](../../api-ref/authentication.md)
* [Шаблонизация письма](../../operations/send-templated-email.md)