[Документация Yandex Cloud](../../../index.md) > [Yandex Cloud Postbox](../../index.md) > [Справочник API](../index.md) > [REST](index.md) > Массовая отправка писем # Метод SendBulkEmail Отправляет несколько шаблонных писем с [адреса](../../concepts/glossary.md#adress) в каталоге. Нужный каталог определяется по сервисному аккаунту, от имени которого выполняется запрос. В одном запросе передается общий шаблон и набор писем к отправке. Для каждого письма указываются адресаты, данные для подстановки в шаблон, заголовки и метки. ## Запрос {#request} ```http POST /v2/email/outbound-bulk-emails HTTP/2 ``` ### Заголовки запроса {#request-headers} Используйте в запросе [общие заголовки](request-headers.md). ### Тело запроса {#request-body} ```json { "ConfigurationSetName": "string", "FromEmailAddress": "<адрес_отправителя>", "ReplyToAddresses": [ "<адрес_для_ответа>" ], "DefaultEmailTags": [ { "Name": "<имя_метки>", "Value": "<значение_метки>" } ], "DefaultContent": { "Template": { "Headers": [ { "Name": "<заголовок>", "Value": "<значение>" } ], "TemplateContent": { "Html": "<шаблон_HTML>", "Subject": "<шаблон_темы>", "Text": "<шаблон_текста>" }, "TemplateData": "<данные_для_подстановки_в_шаблон>", "Attachments": [ { "FileName": "<имя_файла>", "RawContent": "<содержимое_в_Base64>", "ContentType": "", "ContentDescription": "<описание_вложения>", "ContentDisposition": "<способ_отображения>", "ContentId": "<идентификатор_вложения>", "ContentTransferEncoding": "base64" } ] } }, "BulkEmailEntries": [ { "Destination": { "ToAddresses": [ "<адрес_получателя>" ], "CcAddresses": [ "<адрес_получателя_копии>" ], "BccAddresses": [ "<адрес_получателя_скрытой_копии>" ] }, "ReplacementEmailContent": { "ReplacementTemplate": { "ReplacementTemplateData": "<данные_для_подстановки_в_шаблон>" } }, "ReplacementHeaders": [ { "Name": "<заголовок>", "Value": "<значение>" } ], "ReplacementTags": [ { "Name": "<имя_метки>", "Value": "<значение_метки>" } ] } ] } ``` #| || **Параметр** | **Описание** || || `ConfigurationSetName` | **Тип**: string. Имя конфигурации, которая используется для отправки писем. Если не указано, используется конфигурация, привязанная к адресу Yandex Cloud Postbox. || || `FromEmailAddress` | **Тип**: string. Адрес, с которого отправляются письма. Он должен быть верифицирован. Обязательный параметр. || || `ReplyToAddresses` | **Тип**: array. Адреса, на которые будут отправляться ответы получателей. || || `DefaultEmailTags` | **Тип**: array. Метки, которые применяются ко всем письмам в запросе. * `Name` — имя метки. Тип: string. * `Value` — значение метки. Тип: string. Имя и значение метки могут содержать латинские буквы, цифры, дефис и подчеркивание. Максимальная длина — 256 символов. || || `DefaultContent` | **Тип**: object. Объект с общим содержимым письма. || || `Template` | **Тип**: object. Шаблонный тип. Шаблон письма передается в запросе. || || `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`. || || `TemplateContent` | **Тип**: object. Содержит шаблон письма: * `Html` — шаблон HTML. Тип: string. * `Subject` — шаблон темы. Тип: string. Обязательный параметр. * `Text` — шаблон текста. Тип: string. Необходимо указать хотя бы один параметр: `Html` или `Text`. || || `TemplateData` | **Тип**: string. Данные по умолчанию, которые используются для заполнения шаблона. JSON-объект, сериализованный в строку. || || `Attachments` | **Тип**: array. Список вложений. Указывается только в общем содержимом `DefaultContent.Template` и применяется ко всем письмам в запросе. Переопределить или добавить вложения для отдельного элемента `BulkEmailEntries` нельзя. Каждое вложение описывается объектом со следующими полями: * `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). || || `BulkEmailEntries` | **Тип**: array. Список писем для отправки. В запросе должен быть хотя бы один элемент. || || `Destination` | **Тип**: object. Объект, который содержит адреса для доставки письма. * `ToAddresses` — адреса, на которые отправляется письмо. Тип: array. * `CcAddresses` — адреса, на которые отправляется копия письма. Тип: array. * `BccAddresses` — адреса, на которые отправляется скрытая копия письма. Тип: array. Для каждого элемента `BulkEmailEntries` необходимо указать хотя бы один адрес в `ToAddresses`, `CcAddresses` или `BccAddresses`. || || `ReplacementEmailContent` | **Тип**: object. Данные, которые переопределяют содержимое письма для отдельного элемента `BulkEmailEntries`. || || `ReplacementTemplate` | **Тип**: object. Объект с данными для подстановки в шаблон отдельного письма. || || `ReplacementTemplateData` | **Тип**: string. Данные для заполнения шаблона отдельного письма. JSON-объект, сериализованный в строку. Значения из `ReplacementTemplateData` переопределяют одноименные значения из `TemplateData`. || || `ReplacementHeaders` | **Тип**: array. Заголовки отдельного письма. Они дополняют или переопределяют заголовки из `DefaultContent.Template.Headers`. Формат такой же, как у `Headers`. || || `ReplacementTags` | **Тип**: array. Метки отдельного письма. Они дополняют или переопределяют метки из `DefaultEmailTags`. Формат такой же, как у `DefaultEmailTags`. || |# ### Ограничения {#limits} В методе `SendBulkEmail` действуют ограничения: * Максимальное количество элементов `BulkEmailEntries` в одном запросе — 50. * Максимальное суммарное количество получателей во всех элементах `BulkEmailEntries` — 500. * Максимальный размер `TemplateContent.Subject`, `TemplateContent.Text` и `TemplateContent.Html` суммарно — 1 МБ. * Максимальное количество переменных в шаблоне — 50. В шаблоне используется синтаксис [Handlebars](https://handlebarsjs.com/guide/) с простыми подстановками. ## Ответы {#responses} ### 200 OK {#200} ```json { "BulkEmailEntryResults": [ { "Status": "SUCCESS", "MessageId": "<идентификатор_письма>" }, { "Status": "INVALID_PARAMETER", "Error": "<описание_ошибки>" } ] } ``` #| || **Параметр** | **Описание** || || `BulkEmailEntryResults` | **Тип**: array. Результаты отправки писем. Порядок элементов в ответе соответствует порядку элементов в `BulkEmailEntries` из запроса. || || `Status` | **Тип**: string. Статус обработки отдельного письма. Если письмо принято к отправке, возвращается `SUCCESS`. Если письмо не принято, возвращается статус ошибки, например `INVALID_PARAMETER`. || || `MessageId` | **Тип**: string. Уникальный идентификатор письма. Возвращается для писем со статусом `SUCCESS`. || || `Error` | **Тип**: string. Описание ошибки. Возвращается для писем, которые не были приняты к отправке. || |# Если ошибка относится к запросу целиком, метод возвращает ошибку уровня запроса. Если ошибка относится только к отдельному элементу `BulkEmailEntries`, метод возвращает `200 OK`, а ошибка указывается в соответствующем элементе `BulkEmailEntryResults`. ### Ошибки {#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-bulk-email.md)