Протокол интеграции HTTPs (REST) для отправки транзакционных E-mail сообщений
+7 (812) 326 10 75 Наш офис
8 800 333 10 75 Бесплатно по России
Войти

Протокол интеграции 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 данные о статусах отправленного письма по мере их получения.  

Пример возвращаемых данных:
Данные о доставке письма:
{"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="<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 данные о статусах отправленного письма по мере их получения.  

Пример возвращаемых данных:
Данные о доставке письма:
{"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="<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 данные о статусах отправленного письма по мере их получения.  

Пример возвращаемых данных:
Данные о доставке письма:
{"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

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

Мы используем файлы cookie для персонализации контента и рекламы, а также для анализа трафика сайта. Продолжая использовать наш сайт, вы соглашаетесь с политикой компании в отношении обработки персональных данных и файлов cookie.
Согласен Group 6 Created with Sketch.