SMTP API

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

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

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

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

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

  • passwordapi ключ пользователя либо 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", "es", "ru" и "ua". Для добавления дополнительных языков обращайтесь в техподдержку.
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 - ссылка отписки отключена, в подвал она не добавляется.

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

 

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

  • Максимальный размер письма, отправляемого через SMTP - 10 мегабайт.
  • Не забудьте, что заголовок X-UNIONE, как и все остальные заголовки, должен быть особым образом закодирован по стандарту MIME, если он содержит не-ASCII символы (например, русские буквы). Для большиства языков программирования существуют стандартные функции для этого: например, для PHP это mb_encode_mimeheader.
  • В UniOne существует дополнительное ограничение на заголовки - если заголовок длиннее 300 байт, его надо разбивать на несколько строк, каждая из которых не длиннее 300 байт. Обычно за перенос длинных строк отвечает та же функция, что и за кодирование не-ASCII символов. Для PHP, например, как и в пункте выше, это mb_encode_mimeheader.
  • В письма автоматически подставляется ссылка отписки, если не был передан параметр skip_unsubscribe=1, язык ссылки и страницы отписки совпадает с языком global_language. Информация об отписавшихся email будет возвращаться через webhooks. Также информацию по отписавшимся email можно получить, вызывая методы unsubscribed/check и unsubscribed/list.
  • Обратите внимание, что все получатели, указанные в полях "To:", "CC:", "BCC:" получат свою собственную копию письма и каждая копия будет учтена по вашему тарифному плану. Также подстановки из параметра global_substitutions parameter будут применены к каждой копии, так что при необходимости отправлять персонализированные письма с подстановками мы рекомендуем отправлять одиночные письма.
  • Т.к. тег <body> необходим для отображения содержимого HTML письма в случае наличия тега <html>, мы не пропускаем письма без тега <body>, если был использован тег <html>.

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

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

  • стандартные заголовки "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.