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

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

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 данные об ошибке, в случае получения bounce. Необязательный.

Пример возвращаемых данных:

{"event_time":"2021-04-14 17:06:12","email":"a4123541541udyafguog@stream-telecom.ru","bounce_code":"550","bounce_reason":"5.1.1 Mailbox <a4123541541udyafguog@stream-telecom.ru> does not exist","event_type":"BOUNCED","message_id":"1256",

"id":"4a136076f6b19ce4c7.76309942"}

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="<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 данные об ошибке, в случае получения bounce. Необязательный.

Пример возвращаемых данных:

{"event_time":"2021-04-14 17:06:12","email":"a4123541541udyafguog@stream-telecom.ru","bounce_code":"550","bounce_reason":"5.1.1 Mailbox <a4123541541udyafguog@stream-telecom.ru> does not exist","event_type":"BOUNCED","message_id":"1256",

"id":"4a136076f6b19ce4c7.76309942"}

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="<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 данные об ошибке, в случае получения bounce. Необязательный.

Пример возвращаемых данных:

{"event_time":"2021-04-14 17:06:12","email":"a4123541541udyafguog@stream-telecom.ru","bounce_code":"550","bounce_reason":"5.1.1 Mailbox <a4123541541udyafguog@stream-telecom.ru> does not exist","event_type":"BOUNCED","message_id":"1256",

"id":"4a136076f6b19ce4c7.76309942"}

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

Недостаточно средств