Протокол интеграции 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/)

Stream_Telecom_Email_Transaction__1.0.1.pdf

Функции

POST

HTTP/1.1

Host email-gateway.api.sc/rest/Send/SendMail/

Content-Type: multipart/form-data;

pass=*****

to=test@testmail.com

from_name=Sender

from_email=sender@testmail.com

subject=Тестовое письмо

message=%NAME%,TEST#2

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 данные о статусах отправленного письма по мере их получения. Пример возвращаемых данных: Данные о доставке письма: {"event_time":"2022-11-18 13:55:54","email":"ts@testmail.com", "bounce_code":"","bounce_reason":"","event_type":"DELIVERED", "message_id":"123","id":"738637764b5572ce0.54503949"} Данные об открытии письма: {"event_time":"2022-12-01 02:57:32","email":"ts@testmail.com", "bounce_code":"","bounce_reason":"","event_type":"OPENED", "message_id":"","id":"5f9a636df3a61e1fc3.23735897"}
attachments	Нет	Вложение. Количество файлов вложения не ограничено. Суммарный размер файлов не должен превышать 5 Мб. Допускаются любые файлы, кроме .exe и .php. Использование спецсимволов в названии файлов не рекомендуется. Файлы отправляются стандартным образом в теле POST запроса при обращении к API. Важно! Именем параметра при этом должен быть массив attachments. Например, при отправке запроса с помощью CURL, это будет выглядеть следующим образом: $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="TEST"' \

Пример запроса со всеми параметрами

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="TEST"' \

--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 данные о статусах отправленного письма по мере их получения. Пример возвращаемых данных: Данные о доставке письма: {"event_time":"2022-11-18 13:55:54","email":"ts@testmail.com", "bounce_code":"","bounce_reason":"","event_type":"DELIVERED", "message_id":"123","id":"738637764b5572ce0.54503949"} Данные об открытии письма: {"event_time":"2022-12-01 02:57:32","email":"ts@testmail.com", "bounce_code":"","bounce_reason":"","event_type":"OPENED", "message_id":"","id":"5f9a636df3a61e1fc3.23735897"}
attachments	Нет	Вложение. Количество файлов вложения не ограничено. Суммарный размер файлов не должен превышать 5 Мб. Допускаются любые файлы, кроме .exe и .php. Использование спецсимволов в названии файлов не рекомендуется. Файлы отправляются стандартным образом в теле POST запроса при обращении к API. Важно! Именем параметра при этом должен быть массив attachments. Например, при отправке запроса с помощью CURL, это будет выглядеть следующим образом: $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="TEST"' \

Пример запроса со всеми параметрами

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="TEST"' \

--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 данные о статусах отправленного письма по мере их получения. Пример возвращаемых данных: Данные о доставке письма: {"event_time":"2022-11-18 13:55:54","email":"ts@testmail.com", "bounce_code":"","bounce_reason":"","event_type":"DELIVERED", "message_id":"123","id":"738637764b5572ce0.54503949"} Данные об открытии письма: {"event_time":"2022-12-01 02:57:32","email":"ts@testmail.com", "bounce_code":"","bounce_reason":"","event_type":"OPENED", "message_id":"","id":"5f9a636df3a61e1fc3.23735897"}
attachments	Нет	Вложение. Количество файлов вложения не ограничено. Суммарный размер файлов не должен превышать 5 Мб. Допускаются любые файлы, кроме .exe и .php. Использование спецсимволов в названии файлов не рекомендуется. Файлы отправляются стандартным образом в теле POST запроса при обращении к API. Важно! Именем параметра при этом должен быть массив attachments. Например, при отправке запроса с помощью CURL, это будет выглядеть следующим образом: $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	Недостаточно средств

Протокол интеграции HTTPs (REST) для отправки транзакционных E-mail сообщений

Функции

Точный расчет