Протокол интеграции HTTPs (REST) для отправки транзакционных E-mail сообщений
ВНИМАНИЕ
Для использования данного вида интеграции Вам необходимо зарегистрироваться на серверной платформе Stream Telecom, либо зарегистрироваться через менеджера компании. При регистрации Вам присваивается логин, и тестовое имя отправителя SMS Info, которое будет автоматически удалено, после того как Вы запросите новое имя.
Пароль для интеграции задается в настройках пользователя во вкладке Настройки API.
Общие положения
Серверная платформа Stream Telecom (далее Платформа) и клиент сервиса (далее Клиент) обмениваются HTTPS URL- encoded запросами, используя форматы передач данных JSON в соответствии с принципами REST. Действие над данными задается с помощью методов GET или POST в кодировке UTF-8.
Точка доступа
Запросы КЛИЕНТА должны передаваться на сервер ИСПОЛНИТЕЛЯ по URL: http://email-gateway.api.sc/rest/ (ssl: https://email-gateway.api.sc/rest/)
Функции
POST
HTTP/1.1
Host email-gateway.api.sc/rest/Send/SendMail/
Content-Type: multipart/form-data;
login=testlogin
pass=*****
to=test@testmail.com
from_name=Sender
from_email=sender@testmail.com
subject=Тестовое письмо
message=<p>%NAME%,<b>TEST#2</b></p>
plain_text=TEST
headers={"My_headers":"My_values"}
message_id=1256
delivery_time=2021-04-14 14:25:00
replace={"%NAME%":"Имя"}
domain=testmail.com
callback_url=https://mysite.com/script.php
attachments[0]=@file.jpg
attachments[1]=@file.pdf
Описание параметров запроса
Параметр |
Обязательный параметр |
Описание |
login |
Да |
Логин, присвоенный клиенту. |
pass |
Да |
Пароль api (задается в настройках пользователя). |
to |
Да |
Email-адрес получателя. |
from_name |
Да |
Имя отправителя. |
from_email |
Да |
Email-адрес отправителя. |
subject |
Да |
Тема письма. |
message |
Да |
html-код сообщения. |
plain_text |
Нет |
plain_text версия вашего письма. Если параметр не задан или пуст, будет сгенерирована автоматически из html. |
headers |
Нет |
Массив заголовков, закодированный в формате JSON. |
message_id |
Нет |
id сообщения Заказчика, по которому можно идентифицировать вебхук. |
delivery_time |
Нет |
Дата, когда письмо должно быть доставлено. (Время МСК). Дата в формате yyyy-mm-dd hh:mm:ss. |
replace |
Нет |
Массив, закодированный в формате JSON, в котором используются поля подстановки Заказчика. |
domain |
Нет |
Домен отправки, который будет использоваться для DKIM/SPF подписей. Настраивается в личном кабинете. |
callback_url |
Нет |
Адрес скрипта заказчика, на который будут возвращаться POST данные о статусах отправленного письма по мере их
получения.
|
attachments |
Нет |
Вложение. Количество файлов вложения не ограничено. Суммарный размер файлов не должен превышать 5 Мб. Допускаются любые файлы, кроме *.exe и *.php. Использование спецсимволов в названии файлов не рекомендуется.
Файлы отправляются стандартным образом в теле POST запроса при обращении к API. $post['attachments[0]'] = '@giphy.gif'; $post['attachments[1]'] = '@HTB.mp4'; Даже если прикладываемый файл всего один, он должен передаваться в $post['attachments[0]'], а не в $post['attachments']. |
Пример ответва при корректном запросе
{
"id": "4a136077fbb83f0707.90420944",
"message_id": "1256"
}
Пример ответва при некорректном запросе
{
"Code": 1,
"Desc": "pass can not be empty or null\r\nParameter name: pass"
}
Описание параметров ответа
Наименование поля |
Описание |
id |
Идентификатор сообщения |
message_id |
Идентификатор сообщения, присвоенный Заказчиком. |
Пример запроса только с обязательными параметрами
curl --location --request POST 'https://email-gateway.api.sc/rest/Send/SendMail/' \
--form 'login=" testlogin"' \
--form 'pass="*****"' \
--form 'to="test@testmail.com"' \
--form 'from_name="Sender"' \
--form 'from_email="sender@testmail.com"' \
--form 'subject="Тестовое письмо"' \
--form 'message="<p>TEST</p>"' \
Пример запроса со всеми параметрами
curl --location --request POST 'https://email-gateway.api.sc/rest/Send/SendMail/' \
--form 'login=" testlogin"' \
--form 'pass="*****"' \
--form 'to="test@testmail.com"' \
--form 'from_name="Sender"' \
--form 'from_email="sender@testmail.com"' \
--form 'subject="Тестовое письмо для %NAME%"' \
--form 'message="<p>TEST</p>"' \
--form 'headers="{\"My_headers\":\"My_values\"}"' \
--form 'plain_text="TEST"' \
--form 'message_id="1256"' \
--form 'delivery_time="2021-04-14 14:25:00"' \
--form 'replace="{\"%NAME%\":\"Михаил\"}"' \
--form 'domain="testmail.com"' \
--form 'callback_url="https://mysite.com/script.php"' \
--form 'attachments[0]=@"/file.jpg"' \
--form 'attachments[1]=@"/file.pdf"'
Описание параметров запроса
Параметр |
Обязательный параметр |
Описание |
login |
Да |
Логин, присвоенный клиенту. |
pass |
Да |
Пароль api (задается в настройках пользователя). |
to |
Да |
Email-адрес получателя. |
from_name |
Да |
Имя отправителя. |
from_email |
Да |
Email-адрес отправителя. |
subject |
Да |
Тема письма. |
message |
Да |
html-код сообщения. |
plain_text |
Нет |
plain_text версия вашего письма. Если параметр не задан или пуст, будет сгенерирована автоматически из html. |
headers |
Нет |
Массив заголовков, закодированный в формате JSON. |
message_id |
Нет |
id сообщения Заказчика, по которому можно идентифицировать вебхук. |
delivery_time |
Нет |
Дата, когда письмо должно быть доставлено. (Время МСК). Дата в формате yyyy-mm-dd hh:mm:ss. |
replace |
Нет |
Массив, закодированный в формате JSON, в котором используются поля подстановки Заказчика. |
domain |
Нет |
Домен отправки, который будет использоваться для DKIM/SPF подписей. Настраивается в личном кабинете. |
callback_url |
Нет |
Адрес скрипта заказчика, на который будут возвращаться POST данные о статусах отправленного письма по мере их
получения.
|
attachments |
Нет |
Вложение. Количество файлов вложения не ограничено. Суммарный размер файлов не должен превышать 5 Мб. Допускаются любые файлы, кроме *.exe и *.php. Использование спецсимволов в названии файлов не рекомендуется.
Файлы отправляются стандартным образом в теле POST запроса при обращении к API. $post['attachments[0]'] = '@giphy.gif'; $post['attachments[1]'] = '@HTB.mp4'; Даже если прикладываемый файл всего один, он должен передаваться в $post['attachments[0]'], а не в $post['attachments']. |
Пример ответва при корректном запросе
{
"id": "4a136077fbb83f0707.90420944",
"message_id": "1256"
}
Пример ответва при некорректном запросе
{
"Code": 1,
"Desc": "pass can not be empty or null\r\nParameter name: pass"
}
Описание параметров ответа
Наименование поля |
Описание |
id |
Идентификатор сообщения |
message_id |
Идентификатор сообщения, присвоенный Заказчиком. |
Пример запроса только с обязательными параметрами
curl --location --request POST 'https://email-gateway.api.sc/rest/Send/SendMail/' \
--form 'login=" testlogin"' \
--form 'pass="*****"' \
--form 'to="test@testmail.com"' \
--form 'from_name="Sender"' \
--form 'from_email="sender@testmail.com"' \
--form 'subject="Тестовое письмо"' \
--form 'message="<p>TEST</p>"' \
Пример запроса со всеми параметрами
curl --location --request POST 'https://email-gateway.api.sc/rest/Send/SendMail/' \
--form 'login=" testlogin"' \
--form 'pass="*****"' \
--form 'to="test@testmail.com"' \
--form 'from_name="Sender"' \
--form 'from_email="sender@testmail.com"' \
--form 'subject="Тестовое письмо для %NAME%"' \
--form 'message="<p>TEST</p>"' \
--form 'headers="{\"My_headers\":\"My_values\"}"' \
--form 'plain_text="TEST"' \
--form 'message_id="1256"' \
--form 'delivery_time="2021-04-14 14:25:00"' \
--form 'replace="{\"%NAME%\":\"Михаил\"}"' \
--form 'domain="testmail.com"' \
--form 'callback_url="https://mysite.com/script.php"' \
--form 'attachments[0]=@"/file.jpg"' \
--form 'attachments[1]=@"/file.pdf"'
Описание параметров запроса
Параметр |
Обязательный параметр |
Описание |
login |
Да |
Логин, присвоенный клиенту. |
pass |
Да |
Пароль api (задается в настройках пользователя). |
to |
Да |
Email-адрес получателя. |
from_name |
Да |
Имя отправителя. |
from_email |
Да |
Email-адрес отправителя. |
subject |
Да |
Тема письма. |
message |
Да |
html-код сообщения. |
plain_text |
Нет |
plain_text версия вашего письма. Если параметр не задан или пуст, будет сгенерирована автоматически из html. |
headers |
Нет |
Массив заголовков, закодированный в формате JSON. |
message_id |
Нет |
id сообщения Заказчика, по которому можно идентифицировать вебхук. |
delivery_time |
Нет |
Дата, когда письмо должно быть доставлено. (Время МСК). Дата в формате yyyy-mm-dd hh:mm:ss. |
replace |
Нет |
Массив, закодированный в формате JSON, в котором используются поля подстановки Заказчика. |
domain |
Нет |
Домен отправки, который будет использоваться для DKIM/SPF подписей. Настраивается в личном кабинете. |
callback_url |
Нет |
Адрес скрипта заказчика, на который будут возвращаться POST данные о статусах отправленного письма по мере их
получения.
|
attachments |
Нет |
Вложение. Количество файлов вложения не ограничено. Суммарный размер файлов не должен превышать 5 Мб. Допускаются любые файлы, кроме *.exe и *.php. Использование спецсимволов в названии файлов не рекомендуется.
Файлы отправляются стандартным образом в теле POST запроса при обращении к API. $post['attachments[0]'] = '@giphy.gif'; $post['attachments[1]'] = '@HTB.mp4'; Даже если прикладываемый файл всего один, он должен передаваться в $post['attachments[0]'], а не в $post['attachments']. |
Пример ответва при корректном запросе
{
"id": "4a136077fbb83f0707.90420944",
"message_id": "1256"
}
Пример ответва при некорректном запросе
{
"Code": 1,
"Desc": "pass can not be empty or null\r\nParameter name: pass"
}
Описание параметров ответа
Наименование поля |
Описание |
id |
Идентификатор сообщения |
message_id |
Идентификатор сообщения, присвоенный Заказчиком. |
Текст ошибки |
Описание |
Attachments more 5 Mb |
Превышен суммарный размер вложений в 5 Мегабайт |
Wrong attachment format |
Некорректный формат вложения |
#Parameter# can not be empty or null |
Не указан параметр ('login', 'pass', 'to', 'from_name', 'from_email', 'subject', 'message') |
Not correct email Parameter name: ('to','from_email') |
Некорректно указан адрес (email получателя / email отправителя) |
Not correct format JSON Parameter name: ('headers','replace') |
Некорректный формат JSON (заголовок / переменные подстановки) |
User blocked |
Логин заблокирован |
Access denied |
Доступ запрещен (IP отсутствует в списке разрешенных) |
Unauthorized |
Неверный логин или пароль |
System Error |
Системная ошибка |
Tariff error. No price for this direction. |
Отсутствует тариф для отправки email |
Not enough money |
Недостаточно средств |