Отправка почты через API и SMTP

Отправка почты через сервис Mnogoweb Relay возможна двумя способами:

• Отправка через SMTP-сервер (поддерживается любым ПО)
• Отправка через API (требует интеграции с вашим сайтом или сервисом)

Отправка через SMTP-сервер

Преимущества отправки писем через SMTP-подключение:

• Возможность подключения к любому сайту или сервису
• Не требуется модификация программного кода сайта или сервиса
• Лёгкий переход с другого SMTP-сервера или на собственный SMTP-сервер

Недостатки отправки писем через SMTP-подключение:

• Низкая производительность
• Отсутствие возможности отслеживания ошибок
• Не поддерживается идемпотентность (передача специального ключа, в случае повторной передачи которого письмо не будет отправлено повторно)

Параметры подключения:

Параметры подключения к почтовому серверу по протоколу SMTP предоставляются при подключении к сервису. Ниже представлены стандартные параметры, которые вы можете использовать для ориентира.

• Адрес сервера: mx.mail.r1.mnogoweb.com
• Порт: 587 или 25
• Имя пользователя: любое
• Пароль: предоставляется при подключении
• Шифрование: TLS/STARTTLS при использовании порта 587

Отправка через API

Для отправки писем через API необходима интеграция с используемым вами скриптом или ПО. Отправка производится через обычные POST-запросы к серверу, где параметры письма передаются в виде JSON-объекта.

Параметры подключения:

• URL для отправки запроса: https://api.mnogoweb.com/v1/relay/sends
• Метод: POST
• Заголовки: Authorization: Bearer КЛЮЧ, Content-Type: application/json

Пример тела запроса:

Возможные параметры запроса:

• from — отправитель письма в рамках домена (строка или объект с параметрами name — имя отправителя, email — адрес отправителя).
  
• to — получатели письма (строка или массив со списком адресов).
• cc — получатели, которым нужно отправить копию письма (строка или массив со списком адресов).
• bcc — получатели, которым нужно отправить скрытую копию письма (строка или массив со списком адресов).
• subject — тема письма (строка).
• body_html — тело письма в формате HTML (строка).
• body_text — тело письма в текстовом формате, обязательно если не передано тело в формате HTML, может быть передано в дополнение к body_html для определения двух форматов письма (строка).
• headers — дополнительные заголовки письма (объект из пар ключ-значение).
• attachments — вложения к письму (массив из объектов с параметрами content — закодированное в base64 содержимое вложения, name — имя файла вложения, content_type — MIME-тип файла вложения).

Контроль успешности приёма запроса:

Для определения, был ли запрос к API сервиса успешен, мы рекомендуем проверять статус ответа.

В случае успешного запрос будет возвращён статус 200, а также JSON-объект, содержащий:

• id — ID сообщения в рамках проекта.
• message_id — ID сообщения в рамках почтового сервера (указывается также в заголовках письма).

В случае ошибочного запроса будет возвращён иной статус, а также JSON-объект (кроме фатальных ошибок), содержащий:

• message — текстовое описание ошибки.
• status — код ответа сервера.
• violations — массив из объектов с параметрами property (параметр, в котором допущена ошибка) и message (текстовое описание ошибки).

Возможные коды ответа:

• 200: письмо запланировано к отправке.
• 4xx: ошибка в параметрах запроса.
• 429: превышено количество запросов, необходимо повторить запрос после времени, указанного в заголовке Retry-After.
• 5xx: внутренняя ошибка сервера, необходимо повторить запрос.

Идемпотентность запросов

При взаимодействии с сервисом Mnogoweb Relay через API возможна отправка запросов с ключом идемпотентности. Это гарантирует, что письма не будут задублированы в течение 24 часов.

Для использования функции контроля идемотентности, помимо заголовков Authorization и Content-Type необходимо также передать заголовок X-Idempotency-Key. Значением данного заголовка может быть любая строка, явно определяющая запрос в рамках вашей системы. Например, если вы отправляете письмо о статусе заказа, можно использовать значение order-ID.

В случае повторения запроса с тем же ключом сервер API вернёт id и message_id уже ранее добавленного в очередь письма, а также заголовок X-Idempotency-Short-Circuit: true, определяющий, что такой запрос уже был отправлен в течение последних 24 часов.

Технические ограничения

• Максимальное количество запросов на отправку — 10 в секунду.
• Максимальное количество получателей одного письма — 20.
• Максимальная длина темы письма — 998 символов.
• Максимальный размер body_html, body_text — 2 Мб.
• Максимальный размер письма — 10 Мб (включая весь контент и вложения).
• Максимальное количество файлов во вложениях — 10.
• В параметре headers не могут содержаться заголовки From, To, Cc, Bcc, Sender, Date, Subject, Content-Type, MIME-Version, DKIM-Signature, Return-Path, X-Mailer, X-Originating-IP, Authentication-Result.