SMTP API

SMTP позволяет отправлять до 5000 сообщений в час по одному соединению, максимально разрешённые 10 одновременных соединений дают скорость до 50 000 сообщений в час, против нескольких миллионов в час через Web API. Поэтому если ваш приоритет - скорость, используйте Web API. Но зато интеграция очень проста - протокол SMTP стандартный, достаточно указать несколько параметров соединения.

Параметры соединения по SMTP

  • host: smtp.eu1.unione.io или smtp.us1.unione.io (для пользователей, зарегистрированных на eu1.unione.io и us1.unione.io, соответственно)

  • port: 25, 465 или 587 и только по зашифрованному TLS соединению с рекомендуемой версией 1.2 или выше. Мы не поддерживаем ни открытые SMTP соединения на стандартном порту 25, ни шифрованные SSL-соединения по соображениям безопасности. Поддержка TLS версий 1.0 и 1.1 будет прекращена в середине 2021 года.

  • username: user_id (его можно увидеть в левом верхнем углу экрана под email, залогинившись в личный кабинет) либо project_id (его можно узнать с помощью методов project/createproject/get или project/list).

  • password: api ключ пользователя либо project_api_key (его можно узнать с помощью методов project/createproject/get или project/list).

  • encoding: используйте кодировку UTF-8

Расширенные возможности

Через SMTP можно слать как обычные письма, так и пользоваться расширенными возможностями UniOne - подстановками, шаблонами, а также управлять отслеживанием прочтений и переходов.

Для того, чтобы использовать расширенные возможности, вам надо передать дополнительный заголовок X-UNIONE, где в JSON-формате могут присутствовать многие параметры, аналогичные email/send, плюс дополнительный параметр "global_language". Пример:

{
  "global_language": "en",
  "template_engine": "velocity",
  "global_substitutions": {
    "DiscountCode":"XMAS"
  },
  "global_metadata": {
    "meta-campaign": "transactional"
  },
  "track_links":1,
  "track_read":1,
  "skip_unsubscribe":0
}

Параметры, поддерживаемые в JSON в заголовке X-UNIONE

Название Тип Описание
global_language Опциональная строка Язык для ссылок отписки, глобально для всех получателей. По умолчанию - "en". Поддерживаются "en" и "ru", для добавления дополнительных языков обращайтесь в техподдержку.
template_engine Опциональная строка Параметр для выбора шаблонизатора для тела письма (и HTML, и plaintext, и AMP версий), а также для полей Subject, Mail From, Mail To. От шаблонизатора зависит синтаксис подстановок, передаваемых в global_substitutions. Принимает значения: “simple” и “velocity”. Если параметр не передавать, будет взято значение по умолчанию “simple”. 
global_substitutions Опциональный объект Объект для передачи подстановок в формате "имя":"значение".
global_metadata Опциональный объект Объект для передачи метаданных в формате: “имя”: “значение”. Метаданные не фигурируют ни в каких ссылках или заголовках письма, но UniOne запоминает их и возвращает в Webhook
track_links Опциональное число
  • 0 - трекинг кликов отключен
  • 1 - трекинг кликов включен (значение по умолчанию)
track_read Опциональное число
  • 0 - трекинг прочтений отключен
  • 1 - трекинг прочтений включен (значение по умолчанию)
skip_unsubscribe Опциональный логический
  • 0 - отключение ссылки отписки не производится, т.е. в подвал HTML-части письма автоматически добавляется примечание для получателя со ссылкой отписки (значение по умолчанию)
  • 1 - ссылка отписки отключена, в подвал она не добавляется.

По умолчанию использование этого параметра для новых аккаунтов и проектов запрещено, нужно предварительно обратится в техподдержку для разрешения его использования для вашего аккаунта или отдельного проекта.

 

Особенности реализации

В письма автоматически подставляется ссылка отписки, если не был передан параметр skip_unsubscribe=1, язык ссылки и страницы отписки совпадает с языком global_language. Информация об отписавшихся email будет возвращаться через webhooks. Также информацию по отписавшимся email можно получить, вызывая методы unsubscribed/check и unsubscribed/list.

Обратите внимание, что все получатели, указанные в полях "To:", "CC:", "BCC:" получат свою собственную копию письма и каждая копия будет учтена по вашему тарифному плану. Также подстановки из параметра global_substitutions parameter будут применены к каждой копии, так что при необходимости отправлять персонализированные письма с подстановками мы рекомендуем отправлять одиночные письма.

Поддерживаемые заголовки

Пропускаются только следующие заголовки:

  • стандартные заголовки "From", "To", "CC", "BCC", "Reply-To", "Subject" (но они могут быть изменены при использовании подстановок или из-за других особенностей реализации, описанных выше)
  • заголовки "List-Unsubscribe", "List-Subscribe", "List-Help", "List-Owner" и "List-Archive" не удаляются в двух случаях:
    • либо вы ранее запросили в техподдержке принудительное отключение ссылки отписки для user_id/project_id, переданного в качестве SMTP логина
    • либо вы ранее запросили в техподдержке динамическое отключение ссылки отписки для user_id/project_id И передали параметр skip_unsubscribe=1 в заголовке X-UNIONE
  • заголовки, начинающиеся с "X-", в количестве не более 50 штук.

Остальные заголовки удаляются.

Ответ сервера

По выполнению отправки SMTP API возвращает параметр Id, который может быть использован как значение job_id в Webhooks.