Отправка E-mail сообщений

Данная услуга позволяет делать массовые рассылки по адресам электронной почты (e-mail).

Если сообщение отправляется как самостоятельное, не в составе «Каскада», то в параметре type необходимо указать значение email. В параметре target задаются почтовые адреса.

Если сообщение отправляется в составе «Каскада», то в параметре type ставим значение cascade, а в параметре target указываем пары номер_телефона:почтовый_адрес, разделенные между собой двоеточием.

Отправка может быть как простой, используя те же параметры что и при передаче SMS-сообщений, так и расширенной, с применением дополнительного параметра email_message.

Для отправки любого письма через e-mail необходимо задать следующие значения:

  • адрес отправителя — определяется (в порядке приоритета):
    1. значением from параметра email_message (значение можно задавать свое для каждого сообщения);
    2. настройкой в разделе Личный кабинет -> Профиль -> Настройки -> Настройка услуг -> E-mail;
    3. общим адресом в настройках системы (не доступно пользователям)
  • тема письма — определяется (в порядке приоритета):
    1. значением title параметра email_message (значение можно задавать свое для каждого сообщения);
    2. настройкой в разделе Личный кабинет -> Профиль -> Настройки -> Настройка услуг -> E-mail;
    3. значением параметра sender
      Надо учесть, что этот параметр также используется при отправке сообщений других типов, поэтому при каскадной отправке это значение должно содержать имя отправителя, используемое в других мессенджерах.
  • текст письма — определяется (в порядке приоритета):
    1. создается на основе предварительно загруженного шаблона с указанием его идентификатора в template_id параметра email_message (значение можно задавать свое для каждого сообщения).
      Подстановки указываются в placeholders параметра email_message. В данном случае можно использовать любое количество подстановок.
    2. создается на основе предварительно загруженного шаблона в разделе Личный кабинет -> Инструменты -> E-mail шаблоны.
      При этом шаблон должен быть назначен по умолчанию, и в шаблоне должна быть только одна подстановка. Текст для подстановки будет взят из обязательного параметра message.
    3. значением параметра message.
      При этом, текст письма будет передан простым текстом, без какого-либо оформления.

Использование дополнительного параметра email_message

Использовать его можно только при отправке в формате JSON.

JSON-структура параметра
{
	"template_id": "123",
	"from": "example@mydomain.com",
	"title": "Тема письма",
	"placeholders": [
		"placeholder_1": "Текст для замены подстановки 1",
		"placeholder_2": "Текст для замены подстановки 2",
		...
		"placeholder_N": "Текст для замены подстановки N"
	]
}

, где:

  • template_id — идентификатор предварительно загруженного шаблона. Если не указан, то будет взят шаблон по умолчанию, определенный в разделе Личный кабинет -> Инструменты -> E-mail шаблоны. Либо шаблон вообще не будет использован и сообщение будет доставлено в виде простого текста.
  • from — адрес отправителя. Если не указан, то будет использовано значение, определенное в разделе Личный кабинет -> Профиль -> Настройки -> Настройка услуг -> E-mail, либо взято общее системное значение.
  • title — тема письма. Если не указана, то будет использовано значение, определенное в разделе Личный кабинет -> Профиль -> Настройки -> Настройка услуг -> E-mail, либо взято значение, определенное в обязательном параметре sender.
  • placeholders — набор подстановок для выбранного шаблона. Подстановки обязательно должны соответствовать прописанным в шаблоне, как по количеству, так и по написанию. В противном случае сообщение будет отклонено.

Каждый из элементов параметра не обязательный.

Загрузка шаблонов

Шаблоны можно загрузить в систему как через Личный кабинет в разделе Личный кабинет -> Инструменты -> E-mail шаблоны, так и через API.

Для загрузки/изменения шаблона через API необходимо отправить запрос по адресу https://auth.terasms.ru/outbox/saveEmailTemplate/json с параметрами в формате JSON:

{
	"id": "123",
	"template_name": "Название шаблона",
	"template": "Текст шаблона",
	"default": "1"
}

, где:

  • id — идентификатор шаблона.
    Используется только при сохранении изменений в ранее загруженном шаблоне. При первом сохранении не используется или значение устанавливается равным 0 (ноль).
  • template_name — название шаблона. Не обязательный параметр.
    Носит чисто информационный характер. Отображается в Личном кабинете в разделе по управлению E-mail шаблонами.
  • template — шаблон в текстовом или в HTML-формате.
    Как правило, в шаблонах используются изображения. Внедрение изображений должно быть либо в виде ссылки на внешний ресурс, либо путем интеграции в HTML.
    В личном кабинете имеется простой HTML-редактор, однако рекомендуется использовать специальные инструменты для создания качественных шаблонов.
  • default — установка шаблона по умолчанию. Не обязательный параметр.
    Если установлено значение равное 1, то шаблон будет использоваться как шаблон по умолчанию. При этом, если ранее был установлен иной шаблон по умолчанию, то прежний шаблон лишится этого статуса.

При успешной записи шаблона будет возвращен его идентификатор. В противном случае будет выдано сообщение об ошибке.

Управление парами значений Номер_телефона/Адрес_почты

Функция предназначена только для случаев, когда e-mail сообщения отправляются в составе «Каскада».

Как известно, в качестве получателя сообщений в электронной почте используются адреса вида example@mydomain.com, а для других типов сообщений получатель указывается как номер телефона. Для правильной работы «Каскада», в данном случае, необходимы оба варианта. Поэтому в нашей системе реализованы 2 варианта решения проблемы:

  1. Указание в параметре target, в качестве значения, пары номер_телефона:почтовый_адрес. Разделитель - двоеточие. После передачи такого значения пара будет сохранена в системе.
    К одному номеру можно "привязать" несколько почтовых адресов. В этом случае будет отправлено одно письмо, где в качестве получателей будут все указанные адреса.
    Пример: 79871234567:box1@domain.com;box2@anotherdomain.me
  2. Предварительно загрузить в систему варианты соответствий номеров и адресов. После этого, в параметре target достаточно просто указать номер телефона, почтовый адрес будет взят из ранее загруженных данных.

Добавление

GET/POST запрос по адресу https://auth.terasms.ru/outbox/setRelationsPhoneEmail.
В качестве параметров (помимо авторизации), надо указать пары номер_телефона=адрес_почты.
Пример: https://auth.terasms.ru/outbox/setRelationsPhoneEmail?login=***&password...@anotherdomain.me

После выполнения запроса будет показано количество сохраненных пар.

Вывод сохраненных значений

GET/POST запрос по адресу https://auth.terasms.ru/outbox/getRelationsPhoneEmail.
В качестве параметров (кроме авторизации), можно указать phone и/или email, чтобы найти значения пар конкретных номеров и/или почтовых адресов. Если дополнительные параметры не указывать, то будут показаны все сохраненные пары.

Пример: https://auth.terasms.ru/outbox/getRelationsPhoneEmail?login=***&password...

Результат выполнения — данные в формате CSV:
Номер телефона;Почтовый адрес;Дата и время записи
79871234567;box1@domain.com;2019-01-01 10:01:11
79871234567;box2@anotherdomain.me;2019-01-01 10:01:11

Удаление

GET/POST запрос по адресу https://auth.terasms.ru/outbox/deleteRelationsPhoneEmail.
Параметры аналогичные методу добавления. Удаляются только конкретные пары.

После успешного выполнения операции будет отдано сообщение "Done".