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

ВНИМАНИЕ

Для использования данного вида интеграции Вам необходимо зарегистрироваться на серверной платформе Stream Telecom, либо зарегистрироваться через менеджера компании. При регистрации Вам присваивается логин, и тестовое имя отправителя SMS Info, которое будет автоматически удалено, после того как Вы запросите новое имя.

Пароль для интеграции задается в настройках пользователя во вкладке Настройки API.

Общие положения

Серверная платформа Stream Telecom (далее Платформа) и клиент сервиса (далее Клиент) обмениваются HTTPS URL- encoded запросами, используя форматы передач данных JSON в соответствии с принципами REST. Действие над данными задается с помощью методов GET или POST в кодировке UTF-8.

Точка доступа

Запросы КЛИЕНТА должны передаваться на сервер ИСПОЛНИТЕЛЯ по URL: http://gateway.api.sc/rest/
(ssl: https://gateway.api.sc/rest/)


Документация по интеграции транзакционных Email рассылок.pdf

Функции

POST

HTTP/1.1

Host 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://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://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

Идентификатор сообщения, присвоенный Заказчиком.

Пример запроса только с обязательными параметрами

<?php

$curl = curl_init();

curl_setopt_array($curl, array(

CURLOPT_URL => 'https://gateway.api.sc/rest/Send/SendMail/',

CURLOPT_RETURNTRANSFER => true,

CURLOPT_TIMEOUT => 60,

CURLOPT_CUSTOMREQUEST => 'POST',

CURLOPT_POSTFIELDS => array(

'login' => testlogin',

'pass' => *****,

'to' => 'test@testmail.com',

'from_name' => 'Sender',

'from_email' => 'sender@testmail.com',

'subject' => 'Тестовое письмо для ',

'message' => '<p>TEST</p>'),

));

$response = curl_exec($curl);

curl_close($curl);

echo $response;


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

<?php

$curl = curl_init();

curl_setopt_array($curl, array(

CURLOPT_URL => 'https://gateway.api.sc/rest/Send/SendMail/',

CURLOPT_RETURNTRANSFER => true,

CURLOPT_TIMEOUT => 60,

CURLOPT_CUSTOMREQUEST => 'POST',

CURLOPT_POSTFIELDS => array(

'login' => ' testlogin',

'pass' => '*****',

'to' => 'test@testmail.com',

'from_name' => 'Sender',

'from_email' => 'sender@testmail.com',

'subject' => 'Тестовое письмо для %NAME%',

'message' => '<p>TEST</p>',

'headers' => '{"My_headers":"My_values"}',

'plain_text' => 'TEST',

'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]'=> new CURLFILE('/file.jpg'),

'attachments[1]'=> new CURLFILE('/file.pdf')),

));

$response = curl_exec($curl);

curl_close($curl);

echo $response;


Параметры

Описание

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

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