SMTP API

SMTP позволяет отправлять до 3000 сообщений в час по одному соединению, максимально разрешённые 50 одновременных соединений дают скорость до 150 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/create, project/list).

  • passwordapi ключ пользователя либо project_api_key (его можно узнать из списка проектов или с помощью методов project/create, project/list).

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

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

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

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

{
  "global_language": "en",
  "template_engine": "velocity",
"template_id": "37f186b3-1de2-4202-ab37-f8dd0b36ed68",   "global_substitutions": {   "DiscountCode":"XMAS"   },   "global_metadata": {   "meta-campaign": "transactional"   },   "track_links":1,   "track_read":1, "skip_unsubscribe":0 }

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

Название Тип Описание
global_language Опциональная строка Язык для ссылок отписки, глобально для всех получателей. По умолчанию - "en". Поддерживаются be, de, en, es, fr, it, pl, pt, ru, ua, kz. Для добавления дополнительных языков обращайтесь в техподдержку.
template_engine Опциональная строка Параметр для выбора шаблонизатора для тела письма (и HTML, и plaintext, и AMP версий), а также для полей Subject, Mail From, Mail To. От шаблонизатора зависит синтаксис подстановок, передаваемых в global_substitutions. Принимает значения: “simple” и “velocity”. Если параметр не передавать, будет взято значение по умолчанию “simple”. 
template_id Опциональная строка Уникальный идентификатор шаблона, созданного ранее методом template/set или через веб-интерфейс. Обратите внимание, при передаче параметра template_id, из указанного вами шаблона будет использоваться только body. Поля "From", "To", "Reply-To", "Subject" указанные в шаблоне будут проигнорированы. 
global_substitutions Опциональный объект Объект для передачи подстановок в формате "имя":"значение".
global_metadata Опциональный объект Объект для передачи метаданных в формате: “имя”: “значение”. Метаданные не фигурируют ни в каких ссылках или заголовках письма, но UniOne запоминает их и возвращает в webhook
track_links Опциональное число
  • 0 - трекинг кликов отключен
  • 1 - трекинг кликов включен (значение по умолчанию)
track_read Опциональное число
  • 0 - трекинг прочтений отключен
  • 1 - трекинг прочтений включен (значение по умолчанию)
skip_unsubscribe Опциональное число
  • 0 - отключение ссылки отписки не производится, т.е. в подвал HTML-части письма автоматически добавляется примечание для получателя со ссылкой отписки (значение по умолчанию)
  • 1 - ссылка отписки отключена, в подвал она не добавляется.

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

strict Опциональный логический

Параметр для определения метода обработки заголовков "To:", "CC:", "BCC:" (см. Особенности реализации).

  • false - все получатели, указанные в полях "To:", "CC:", "BCC:" получат свою собственную копию письма (значение по умолчанию)
  • true - строгое соответствие SMTP-стандарту
tags Опциональный массив Массив из строк, до 50 символов в каждой. Максимум 4 строки в массиве, строки должны быть уникальны. Для каждого аккаунта/проекта разрешено не более 10 000 меток, при превышении метод email/send будет возвращать ошибку. Метки могут использоваться для категоризации писем по выбранным вами критериям. Метки передаются при вызове методов event-dump.

 

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

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

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

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

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

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

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

По выполнению отправки SMTP API возвращает параметр Id.