Общие сведения
Через API внешние приложения получают доступ к системе управлению списками получателей, отправке одиночных email сообщений, рассылок, а также прочий функционал для работы со списками получателей и статистикой рассылок
Базовый URL
Базовый URL для всех запросов
Альтернативный базовый URL для всех запросов
https://api-reserve.msndr.net/v1
Используйте альтернативный URL в случае, когда ваш IP заблокирован или имеет ограничения со стороны РКН.
Аутентификация
Для удостоверения подлинности запросов, в каждом обращении к API необходимо отправлять заголовок содержащий Ваш ключ.
Authorization: Bearer $API_TOKEN
Ключ для доступа к API можно получить в личном кабинете.
Держите Ваш ключ для доступа к API в секрете.
Формат обмена данных
Для обмена данными используется формат JSON, поэтому, в каждом запросе должен присутствовать заголовок
Content-Type: application/json
Все данные от сервера возвращаются так же, в формате JSON.
Получение списков данных (Collection)
Списки данных (Collection) - постраничный способ выдачи данных, используемый в некоторых методах. Для управления страницами выдачи списка данных в заголовках запроса необходимо передавать параметры pagenumber и pagesize:
Пример запроса
curl -X GET https://api.msndr.net/v1/email/lists?page_number=2&page_size=3 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Поддерживаемые параметры
Параметр | Описание |
---|---|
page_number | Номер запрашиваемой страницы. По умолчанию: 1 |
page_size | Количество записей на странице. По умолчанию: 25 |
Если параметр page_size превышает максимально допустимый размер, то сервер ответит ошибкой со статусом 412:
{"errors":[{"code":412,"detail":"Page size is too big. Max value is 100"}]}
По умолчанию максимальный page_size равняется 100, если в описании конкретного метода не указано другое.
При выполнении запроса с использованием списка данных ответ будет возвращен в виде структуры:
Пример ответа со списком данных (Collection)
{"total_count":23,"total_pages":7,"page_number":2,"page_size":3,"collection":[{"id":1,"title":"My Recipients"},{"id":2,"title":"My Recipients #2"},{"id":3,"title":"My Recipients #3"}]}
Ключ | Описание |
---|---|
total_count | Общее количество элементов "collection" |
total_pages | Количество страниц |
page_number | Номер текущей страницы |
page_size | Количество записей на странице |
collection | Массив возвращаемых данных |
Обработка ответа
Обработка ответа может осуществляться при проверки кода состояния HTTP запроса. Так же в случае неуспешного выполнения запроса, ответ содержит массив данных c описанием ошибок в формате JSON.
Пример ответа с ошибками
{"errors":[{"code":400,"detail":"subject is empty"}]}
Коды ответов
Код | Описание |
---|---|
2xx | Запрос успешно выполнен |
400 | Неверные параметры |
401 | Аутентификация не пройдена |
402 | Недостаточно средств |
404 | Ресурс не найден |
415 | Неподдерживаемый тип данных |
422 | Ресурс не может быть обработан |
500 | Неизвестная ошибка |
Ограничения
Для предотвращения отправки нежелательных писем (спам), отправляемых по API или SMTP, в системе предусмотрен механизм приостановки отправки сообщений. Если для вашей учетной записи активировался механизм ограничения отправки, в личном кабинете в разделе API и SMTP, вы увидите предупреждение. Так же, при отправке письма в момент действующего ограничения вы увидите соответствующий ответ. Если вы считаете, что ограничения введены ошибочно, обратитесь в службу технической поддержи.
Примеры ответов
Для API:
{"errors":[{"code":429,"detail":"Too many messages. Try again in 92 seconds."}]}
Для SMTP:
$ telnet smtp.msndr.net 25
Trying 95.213.163.242...
Connected to smtp.msndr.net.
Escape character is '^]'.
220 smtp.msndr.net ESMTP service ready
ehlo sender
250-smtp.msndr.net
250-STARTTLS
250-AUTH PLAIN LOGIN
250-PIPELINING
250 8BITMIME
auth plain AHVzZXJAZXhhbXBsZS5vcmcAc29tZS1zdXBlci1wdXBlci1zZWNyZXQta2V5
550 Too many messages. Try again in 92 seconds.
Connection closed by foreign host.
Готовые решения
Ruby
Если вы используете Ruby, то вы можете воспользоваться библиотекой rusender-ruby.
Информация о балансе
Пример запроса
curl -X GET https://api.msndr.net/v1/email/balance \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{"tariff":{"subscribers":{"total":1000,"available":997},"credits":0,"expires_at":1629273060},"balance":12965.96}
GET /email/balance
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
tariff.subscribers.total | Итоговое количество подписчиков |
tariff.subscribers.available | Доступное количество подписчиков |
credits | Количество писем |
expires_at | Время окончания действия тарифа (timestamp) |
balance | Сумма на балансе |
Одиночные сообщения
Отправка одиночного email сообщения
Пример JSON для запроса
{"from_email":"alice@example.org","from_name":"Alice","to":"bob@example.org","subject":"Hello","text":"Hello, Bob!","html":"<h1>Hello, Bob!</h1>","payment":"credit","smtp_headers":{"Client-Id":"123"}}
Пример запроса
curl -X POST https://api.msndr.net/v1/email/messages \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{"id":1,"from_email":"alice@example.org","from_name":"Alice","to":"bob@example.org","subject":"Hello","text":"Hello, Bob!","html":"<h1>Hello, Bob!</h1>","attachments":[],"status":"queued","events":{"open":1,"redirect":{"http://foo.com":2,"http://bar.com":3},"spam":1,"unsubscribe":1}}
Пример запроса для отправки сообщения с вложениями
curl -X POST https://api.msndr.net/v1/email/messages \
-H 'Authorization: Bearer $API_TOKEN' \
-F from_email=from@example.com \
-F to=to@example.com \
-F subject='Mail with attachments' \
-F text='Hello world' \
-F attachments[]=@/path/to/file1 \
-F attachments[]=@/path/to/file2 \
-F smtp_headers[Client-Id]=123
POST /email/messages
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
from_email | Да | |
from_name | ||
to | Да | |
subject | Да | |
text | Должен присутствовать хотя бы один параметр:text илиhtml |
|
html | Должен присутствовать хотя бы один параметр:text илиhtml |
|
attachments | Массив с вложениями. Поддерживается только для запросов с типом содержимого multipart/form-data | |
payment |
Способ тарификации сообщения. Возможные значения:
Значение по умолчанию:
|
|
smtp_headers | Список заголовков, которые будут добавлены к отправляемому SMTP сообщению |
Способы тарификации сообщения
Значение | Описание |
---|---|
subscriber_priority | Тарифицируется "подписчик", если не доступны "подписчики", используется "письмо". Если нет "писем", возвращается ошибка. |
credit_priority | Тарифицируется "письмо". Если нет "писем", используется "подписчик". Если нет "подписчиков", возвращается ошибка. |
subscriber | Тарифицируется "подписчик". Если нет "подписчиков", возвращается ошибка. |
credit | Тарифицируется "письмо". Если нет "писем", возвращается ошибка. |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор сообщения |
from_email | Адрес отправителя |
from_name | Имя отправителя |
to | Адрес получателя |
subject | Тема |
text | Текстовая версия сообщения |
html | HTML версия сообщения |
attachments | Массив имен вложенных файлов |
status | Статус сообщения |
events | Информация о событиях |
Статусы сообщения
Статус | Описание |
---|---|
queued | Принято в очередь |
sent | Отправлено, ожидается подтверждение доставки |
delivered | Доставлено |
skipped | Не отправлено. Получатель отписался или находится в списке проблемных получателей |
soft_bounced | Не доставлено. Временно отклонено принимающей стороной |
hard_bounced | Сообщение не может быть доставлено |
Информация о событиях
Событие | Описание |
---|---|
open | Сообщение прочитано |
redirect | Получатель перешел по ссылке |
spam | Сообщение помечено как спам |
unsubscribe | Пользователь отписался |
Обратите внимание на то, что при отправке сообщений сервер может вернуть ответ со статусом 429. Это означает, что вы превысили количество сообщений, разрешенное к отправке, в единицу времени. Результат отправки сообщений влияет на лимит сообщений в единицу времени. Таким образом, если вы отправляете письма только вашим клиентам, только на существующие адреса, не рассылаете спам и тп, то разрешенное количество сообщений в единицу времени для вашего аккаунта будет увеличиваться, и наоборот.
Получение информации о сообщении
Пример запроса
curl -X GET https://api.msndr.net/v1/email/messages/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{"id":1,"from_email":"alice@example.org","from_name":"Alice","to":"bob@example.org","subject":"Hello","text":"Hello, Bob!","html":"<h1>Hello, Bob!</h1>","status":"queued","events":{"open":1,"redirect":{"http://foo.com":2,"http://bar.com":3},"spam":1,"unsubscribe":1}}
GET /email/messages/:id
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
from_email | Адрес отправителя |
from_name | Имя отправителя |
to | Адрес получателя |
subject | Тема |
text | Текстовая версия сообщения |
html | HTML версия сообщения |
status | Статус сообщения |
events | Информация о событиях |
Статусы сообщения
Статус | Описание |
---|---|
queued | Принято в очередь |
sent | Отправлено |
delivered | Доставлено |
skipped | Не отправлено |
soft_bounced | Сообщение не доставлено |
hard_bounced | Сообщение не может быть доставлено |
Информация о событиях
Событие | Описание |
---|---|
open | Сообщение прочитано |
redirect | Получатель перешел по ссылке |
spam | Сообщение помечено как спам |
unsubscribe | Пользователь отписался |
Отправка одиночного сообщения по шаблону
В личном кабинете в разделе "Автоматизация", выберите "Одиночное по шаблону" и создайте шаблон письма. Отправляйте письма по этому шаблону с параметрами. Для подстановки параметра в шаблоне используйте конструкцию [%имя параметра%], например [%name%], [%age%] и т.д.
Пример JSON для запроса
{"to":"bob@example.org","payment":"credit","params":{"name":"Ivan","age":"33"}}
POST /email/templates/:template_id/messages
где :template_id - идентификатор шаблона
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
to | email получателя | Да |
params | Параметры подстановки | Нет |
payment |
Способ тарификации сообщения. Возможные значения:
Значение по умолчанию:
|
Нет |
Пример запроса
curl -X POST https://api.msndr.net/v1/email/templates/1/messages \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор сообщения |
to | Адрес получателя |
status | Статус сообщения |
events | Информация о событиях |
Статусы сообщения
Статус | Описание |
---|---|
queued | Принято в очередь |
sent | Отправлено, ожидается подтверждение доставки |
delivered | Доставлено |
skipped | Не отправлено. Получатель отписался или находится в списке проблемных получателей |
soft_bounced | Не доставлено. Временно отклонено принимающей стороной |
hard_bounced | Сообщение не может быть доставлено |
Информация о событиях
Событие | Описание |
---|---|
open | Сообщение прочитано |
redirect | Получатель перешел по ссылке |
spam | Сообщение помечено как спам |
unsubscribe | Пользователь отписался |
Обратите внимание на то, что при отправке сообщений сервер может вернуть ответ со статусом 429. Это означает, что вы превысили количество сообщений, разрешенное к отправке, в единицу времени. Результат отправки сообщений влияет на лимит сообщений в единицу времени. Таким образом, если вы отправляете письма только вашим клиентам, только на существующие адреса, не рассылаете спам и тп, то разрешенное количество сообщений в единицу времени для вашего аккаунта будет увеличиваться, и наоборот.
Способы тарификации сообщения
Значение | Описание |
---|---|
subscriber_priority | Тарифицируется "подписчик", если не доступны "подписчики", используется "письмо". Если нет "писем", возвращается ошибка. |
credit_priority | Тарифицируется "письмо". Если нет "писем", используется "подписчик". Если нет "подписчиков", возвращается ошибка. |
subscriber | Тарифицируется "подписчик". Если нет "подписчиков", возвращается ошибка. |
credit | Тарифицируется "письмо". Если нет "писем", возвращается ошибка. |
Шаблоны
Получение списка шаблонов
Пример запроса
curl -X GET https://api.msndr.net/v1/email/templates \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Данный метод поддерживает постраничную выдачу результатов.
Пример ответа в случае успеха
{"total_count":3,"total_pages":1,"page_number":1,"page_size":25,"collection":[{"id":1,"name":"My Template"}]}
GET /email/templates
Группы получателей
Создание группы
Пример JSON для запроса
{"title":"My Recipients"}
Пример запроса
curl -X POST https://api.msndr.net/v1/email/lists \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{"id":1,"title":"My Recipients"}
POST /email/lists
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
title | Название группы получателей. Должно быть уникальным | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор созданной группы |
title | Название группы |
Получение списка групп
Пример запроса
curl -X GET https://api.msndr.net/v1/email/lists \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Данный метод поддерживает постраничную выдачу результатов.
Пример ответа в случае успеха
{"total_count":3,"total_pages":1,"page_number":1,"page_size":25,"collection":[{"id":1,"title":"My Recipients"},{"id":2,"title":"My Recipients #2"},{"id":3,"title":"My Recipients #3"}]}
GET /email/lists
Ответ сервера
Ответ сервера содержит коллекцию групп получателей. Каждый элемент содержит следующие атрибуты:
Атрибут | Описание |
---|---|
id | Идентификатор группы |
title | Название группы |
Получение информации о группе
Пример запроса
curl -X GET https://api.msndr.net/v1/email/lists/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{"id":1,"title":"My Recipients"}
GET /email/lists/:id
где :id - идентификатор группы для запроса информации
Ответ сервера
Ответ сервера в формате JSON содержит следующие атрибуты:
Атрибут | Описание |
---|---|
id | Идентификатор группы |
title | Название группы |
Удаление группы
Пример запроса
curl -X DELETE https://api.msndr.net/v1/email/lists/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
DELETE /email/lists/:id
где :id - идентификатор группы для запроса информации
Ответ сервера
В случае успешного удаления сервер вернет пустой ответ со статусом 204.
Редактирование группы
Пример JSON для запроса
{"title":"New Title"}
Пример запроса
curl -X PATCH https://api.msndr.net/v1/email/lists/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
-d '...JSON...'
Пример ответа в случае успеха
{"id":1,"title":"New Title"}
PATCH /email/lists/:id
где :id - идентификатор группы для запроса информации
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
title | Название группы получателей. Должно быть уникальным | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор созданной группы |
title | Название группы |
Параметры группы получателей
Создание параметра
Пример JSON для запроса
{"title":"Age","kind":"numeric"}
Пример запроса
curl -X POST https://api.msndr.net/v1/email/lists/1/parameters \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{"id":11,"title":"Age","kind":"numeric","list_id":15}
POST /email/lists/:id/parameters
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
title | Да | |
kind | Возможные значения:string numeric date boolean geo Значение по умолчанию: string |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
title | Название |
kind | Тип |
Список параметров
Пример запроса
curl -X GET https://api.msndr.net/v1/email/lists/1/parameters \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Данный метод поддерживает постраничную выдачу результатов.
Пример ответа в случае успеха
{"total_count":2,"total_pages":1,"page_number":1,"page_size":25,"collection":[{"id":1,"title":"Name","kind":"string","list_id":1},{"id":2,"title":"Age","kind":"numeric","list_id":1}]}
GET /email/lists/:id/parameters
Ответ сервера
Ответ сервера содержит коллекцию параметров группы получателей. Каждый элемент содержит следующие атрибуты:
Атрибут | Описание |
---|---|
id | Идентификатор |
title | Название |
kind | Тип |
Изменение параметра
Пример JSON для запроса
{"title":"Age","kind":"numeric"}
Пример запроса
curl -X PATCH https://api.msndr.net/v1/email/lists/11/parameters/15 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{"id":11,"title":"Age","kind":"numeric","list_id":15}
PATCH /email/lists/:list-id/parameters/:id
где :list-id - идентификатор группы, :id - идентификатор параметра
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
title | ||
kind | Возможные значения:string numeric date boolean geo При изменении типа параметра, соответствующие значения обнулятся |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
title | Название |
kind | Тип |
Удаление параметра
Пример запроса
curl -X DELETE https://api.msndr.net/v1/email/lists/11/parameters/15 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
DELETE /email/lists/:list-id/parameters/:id
где :list-id - идентификатор группы, :id - идентификатор параметра
Получатели
Создание получателя
Пример JSON для запроса
{"email":"alice@example.org","unconfirmed":true,"values":[{"parameter_id":"1","value":"Alice"},{"parameter_id":"2","value":"22"}]}
Пример запроса
curl -X POST https://api.msndr.net/v1/email/lists/1/recipients \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{"id":1,"email":"alice@example.org","confirmed":false,"list_id":1,"status":"active","values":[{"value":"Alice","kind":"string","parameter_id":1},{"value":22.0,"kind":"numeric","parameter_id":2}]}
POST /email/lists/:id/recipients
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
Да | ||
unconfirmed | Создать неподтвержденного получателя. Необходимо задать любое значение, например, true, t или 1. По умолчанию создается подтвержденный получатель | Нет |
values | Массив значений для параметров |
Элементы массива значений
Параметр | Описание | Обязательный |
---|---|---|
parameter_id | ID параметра группы получателей | Да |
value | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
Адрес | |
confirmed | Подтвержден получатель или нет |
status | Статус получателя. Возможные значения: active, incorrect, unconfirmed, unsubscribed |
values | Массив значений |
Элементы массива значений
Параметр | Описание |
---|---|
parameter_id | ID параметра группы получателей |
kind | Тип параметра |
value | Значение |
Информация о получателе
Данный метод позволяет получить информацию о получателе по ID.
Пример запроса
curl -X GET https://api.msndr.net/v1/email/lists/1/recipients/2 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{"id":2,"email":"alice@example.org","confirmed":false,"list_id":1,"status":"active","values":[{"value":"Alice","kind":"string","parameter_id":1},{"value":22.0,"kind":"numeric","parameter_id":2}]}
GET /email/lists/:list_id/recipients/:id
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
list_id | ID группы | Да |
id | ID получателя | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
Адрес | |
confirmed | Подтвержден получатель или нет |
status | Статус получателя. Возможные значения: active, incorrect, unconfirmed, unsubscribed |
values | Массив значений |
Элементы массива значений
Параметр | Описание |
---|---|
parameter_id | ID параметра группы получателей |
kind | Тип параметра |
value | Значение |
Обновление получателя
Пример JSON для запроса
{"email":"alice@example.org","values":[{"parameter_id":"1","value":"Alice"},{"parameter_id":"2","destroy":"true"}]}
Пример запроса
curl -X PATCH https://api.msndr.net/v1/email/lists/1/recipients/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{"id":1,"email":"alice@example.org","confirmed":true,"status":"active","list_id":1,"values":[{"value":"Alice","kind":"string","parameter_id":1}]}
PATCH /email/lists/:list_id/recipients/:id
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
Нет | ||
values | Массив значений для параметров |
Элементы массива значений
Параметр | Описание | Обязательный |
---|---|---|
parameter_id | ID параметра группы получателей | Да |
value | Не может быть одновременно использован с параметром destroy | Нет |
destroy | Используется для удаления значения. Для удаления значения необходимо задать любое значение, например, true, t или 1. Не можеть быть использован одновременно с параметром value | Нет |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
Адрес | |
confirmed | Подтвержден получатель или нет |
status | Статус получателя. Возможные значения: active, incorrect, unconfirmed, unsubscribed |
values | Массив значений |
Элементы массива значений
Параметр | Описание |
---|---|
parameter_id | ID параметра группы получателей |
kind | Тип параметра |
value | Значение |
Список получателей
Пример запроса
curl -X GET https://api.msndr.net/v1/email/lists/1/recipients \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Данный метод поддерживает постраничную выдачу результатов. Максимальный page_size равняется 1000.
Пример ответа в случае успеха
{"total_count":2,"total_pages":1,"page_number":1,"page_size":25,"collection":[{"id":1,"email":"alice@example.org","confirmed":true,"status":"active","list_id":1,"values":[{"value":"Alice","kind":"string","parameter_id":9},{"value":22.0,"kind":"numeric","parameter_id":10}]},{"id":2,"email":"bob@example.org","confirmed":true,"status":"active","list_id":1,"values":[]}]}
GET /email/lists/:id/recipients
Ответ сервера
Ответ сервера содержит коллекцию получателей в группе. Каждый элемент содержит следующие атрибуты:
Атрибут | Описание |
---|---|
id | Идентификатор |
Адрес | |
confirmed | Подтвержден получатель или нет |
status | Статус получателя. Возможные значения: active, incorrect, unconfirmed, unsubscribed |
values | Массив значений |
Элементы массива значений
Параметр | Описание |
---|---|
parameter_id | ID параметра группы получателей |
kind | Тип параметра |
value | Значение |
Удаление получателя
Пример запроса
curl -X DELETE https://api.msndr.net/v1/email/lists/1/recipients/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
DELETE /email/lists/:list_id/recipients/:id
Импорт большого количества получателей
POST /email/lists/:id/recipients/imports
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
recipients | Массив получателей. Максимальный размер 10000 | Да |
run_triggers | Запустить связанные триггеры. Необходимо задать любое значение, например, true, t или 1. | Нет |
Массив получателей
Параметр | Описание | Обязательный |
---|---|---|
Да | ||
values | Массив значений для параметров |
Элементы массива значений
Параметр | Описание | Обязательный |
---|---|---|
parameter_id | ID параметра группы получателей | Да |
value | Да |
Ответ сервера
Параметр | Описание |
---|---|
id | Идентификатор импорта. В дальнейшем может использоваться для получения информации о ходе импорта |
status | Статус импорта |
Пример JSON для запроса
{"recipients":[{"email":"alice@example.org","values":[{"parameter_id":"1","value":"Alice"},{"parameter_id":"2","value":"22"}]},{"email":"bob@example.org","values":[{"parameter_id":"1","value":"Bob"},{"parameter_id":"2","value":"11"}]}]}
Пример запроса
curl -X POST https://api.msndr.net/v1/email/lists/1/recipients/imports \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{"id":7,"status":"queued"}
Поиск получателей
Данный метод позволяет осуществить поиск получателя по email, например, чтобы определить в каких группах есть данный получатель.
Пример запроса
curl -X GET https://api.msndr.net/v1/email/recipients/search?email=foo@bar.com \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{"total_count":2,"total_pages":1,"page_number":1,"page_size":25,"collection":[{"email":"foo@bar.com","recipients":[{"list_id":1,"list_title":"List #1","recipient_id":1},{"list_id":2,"list_title":"List #2","recipient_id":2}]}],"query":"test"}
GET /email/recipients/search
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
Искомый адрес | Да |
Ответ сервера
Ответ сервера содержит коллекцию получателей в группе. Каждый элемент содержит следующие атрибуты:
Атрибут | Описание |
---|---|
Адрес получателя | |
recipients | Массив, содержащий информацию о списках, в которых есть искомый получатель |
Организации
Создание организации
Пример JSON для запроса
{"name":"My Organization","address":"Lenina 40","country":"Russia","city":"Tomsk","phone":"+7-3822-123-456","zip":"634000"}
Пример запроса
curl -X POST https://api.msndr.net/v1/email/organizations \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{"id":1,"name":"My Organization","address":"Lenina 40","country":"Russia","city":"Tomsk","phone":"+7-3822-123-456","zip":"634000","current":true}
POST /email/organizations
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
name | Да | |
address | Да | |
country | Да | |
city | Да | |
phone | Да | |
zip | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Список организаций
Пример запроса
curl -X GET https://api.msndr.net/v1/email/organizations \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Данный метод поддерживает постраничную выдачу результатов.
Пример ответа в случае успеха
{"total_count":1,"total_pages":1,"page_number":1,"page_size":25,"collection":[{"id":1,"name":"My Organization","address":"Lenina 40","country":"Russia","city":"Tomsk","phone":"+7-3822-123-456","zip":"634000","current":true}]}
GET /email/organizations
Ответ сервера
Ответ сервера содержит коллекцию организаций. Каждый элемент содержит следующие атрибуты:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Информация об организации
Пример запроса
curl -X GET https://api.msndr.net/v1/email/organizations/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{"id":1,"name":"My Organization","address":"Lenina 40","country":"Russia","city":"Tomsk","phone":"+7-3822-123-456","zip":"634000","current":true}
GET /email/organizations/:id
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Организация по умолчанию
Пример запроса
curl -X GET https://api.msndr.net/v1/email/organizations/current \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{"id":1,"name":"My Organization","address":"Lenina 40","country":"Russia","city":"Tomsk","phone":"+7-3822-123-456","zip":"634000","current":true}
GET /email/organizations/current
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Задать организацию по умолчанию
Пример запроса
curl -X PATCH https://api.msndr.net/v1/email/organizations/1/current \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{"id":1,"name":"My Organization","address":"Lenina 40","country":"Russia","city":"Tomsk","phone":"+7-3822-123-456","zip":"634000","current":true}
PATCH /email/organizations/:id/current
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Изменение организации
Пример JSON для запроса
{"name":"My Organization","address":"Lenina 40","country":"Russia","city":"Tomsk","phone":"+7-3822-123-456","zip":"634000"}
Пример запроса
curl -X PATCH https://api.msndr.net/v1/email/organizations/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{"id":1,"name":"My Organization","address":"Lenina 40","country":"Russia","city":"Tomsk","phone":"+7-3822-123-456","zip":"634000","current":true}
PATCH /email/organizations/:id
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
name | ||
address | ||
country | ||
city | ||
phone | ||
zip |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Удаление организации
Пример запроса
curl -X DELETE https://api.msndr.net/v1/email/organizations/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
DELETE /email/organizations/:id
Рассылки
Создание рассылки
Пример JSON для запроса
{"from_email":"hello@world.com","subject":"Hello World","text":"Hello World","html":"<h1>Hello World</h1>","lists":[{"id":"1"}]}
Пример запроса
curl -X POST https://api.msndr.net/v1/email/campaigns \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример запроса для создания рассылки с вложениями
curl -X POST https://api.msndr.net/v1/email/campaigns \
-H 'Authorization: Bearer $API_TOKEN' \
-F from_email=from@example.com \
-F subject='Mail with attachments' \
-F html='<h1>Hello world</h1>' \
-F attachments[]=@/path/to/file1 \
-F attachments[]=@/path/to/file2
Пример ответа в случае успеха
{"id":1,"from_email":"hello@world.com","from_name":null,"html":"<h1>Hello World</h1>","text":"Hello World","state":"draft","recipients_count":10,"purchase":{"enable":true,"subscribers":10,"credits":0,"deficit":0},"statistics":{"delivered":1,"bounced":0,"delivering":0,"uniq_open":0,"total_open":0,"last_open_at":nil,"uniq_click":0,"total_click":0,"last_click_at":nil,"unsubscription":0,"spam":0}}
POST /email/campaigns
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
from_email | Да | |
subject | Да | |
from_name | ||
text | ||
html | Да | |
lists | Массив групп получателей | Да |
Элементы массива групп получателей
Параметр | Описание | Обязательный |
---|---|---|
id | ID группы получателей | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
from_email | Адрес отправителя |
from_name | Имя отправителя |
html | |
text | |
state | Статус (рассылка создается в статусе draft) |
recipients_count | Количество получателей |
purchase | Информация о тарификации |
statistics | Статистика |
Статусы
Значение | Описание |
---|---|
draft | Черновик |
pending | На модерации |
delayed | Запланированная |
sending | Отправляется |
canceled | Отменена |
stopped | Остановлена |
completed | Завершена |
archived | В архиве |
Информация о тарификации
Атрибут | Описание |
---|---|
enable | Может принимать значение true (отправка возможна) или false (недостаточно средств) |
subscribers | Количество подписчиков которое будет списано |
credits | Количество кредитов которое будет списано |
deficit | Количество недостающих средств |
Статистика
Атрибут | Описание |
---|---|
delivered | Количество доставленных сообщений |
bounced | Количество недоставленный сообщений |
delivering | Количество доставляющихся сообщений |
uniq_open | Количество уникальных открытий |
total_open | Количество открытий всего |
lastopenat | Timestamp последнего открытия |
uniq_click | Количество уникальных переходов |
total_click | Количество переходов всего |
lastclickat | Timestamp последнего перехода |
unsubscription | Количество отписок |
spam | Количество нажатий кнопки "спам" |
Отправка рассылки
Пример запроса
curl -X PATCH https://api.msndr.net/v1/email/campaigns/1/deliver \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{"id":1,"from_email":"hello@world.com","from_name":null,"html":"<h1>Hello World</h1>","text":"Hello World","state":"sending","recipients_count":10,"purchase":{"enable":true,"subscribers":10,"credits":0,"deficit":0},"statistics":{"delivered":1,"bounced":0,"delivering":0,"uniq_open":0,"total_open":0,"last_open_at":nil,"uniq_click":0,"total_click":0,"last_click_at":nil,"unsubscription":0,"spam":0}}
PATCH /email/campaigns/:id/deliver
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
id | ID созданной рассылки | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
from_email | Адрес отправителя |
from_name | Имя отправителя |
html | |
text | |
state | Статус |
recipients_count | Количество получателей |
purchase | Информация о тарификации |
statistics | Статистика |
Статусы
Значение | Описание |
---|---|
draft | Черновик |
pending | На модерации |
delayed | Запланированная |
sending | Отправляется |
canceled | Отменена |
stopped | Остановлена |
completed | Завершена |
archived | В архиве |
Информация о тарификации
Атрибут | Описание |
---|---|
enable | Может принимать значение true (отправка возможна) или false (недостаточно средств) |
subscribers | Количество подписчиков которое будет списано |
credits | Количество кредитов которое будет списано |
deficit | Количество недостающих средств |
Статистика
Атрибут | Описание |
---|---|
delivered | Количество доставленных сообщений |
bounced | Количество недоставленный сообщений |
delivering | Количество доставляющихся сообщений |
uniq_open | Количество уникальных открытий |
total_open | Количество открытий всего |
lastopenat | Timestamp последнего открытия |
uniq_click | Количество уникальных переходов |
total_click | Количество переходов всего |
lastclickat | Timestamp последнего перехода |
unsubscription | Количество отписок |
spam | Количество нажатий кнопки "спам" |
Список рассылок
Пример запроса
curl -X GET https://api.msndr.net/v1/email/campaigns \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Данный метод поддерживает постраничную выдачу результатов.
Пример ответа в случае успеха
{"total_count":1,"total_pages":1,"page_number":1,"page_size":25,"collection":[{"id":1,"from_email":"test@example.com","from_name":"Test","html":"<p>test</p>","text":"test","state":"draft","recipients_count":10,"purchase":{"enable":true,"subscribers":0,"credits":10,"deficit":0},"statistics":{"delivered":1,"bounced":0,"delivering":0,"uniq_open":0,"total_open":0,"last_open_at":nil,"uniq_click":0,"total_click":0,"last_click_at":nil,"unsubscription":0,"spam":0}}]}
GET /email/campaigns
Ответ сервера
Ответ сервера содержит коллекцию рассылок. Подробнее об элементах коллекции можно прочитать в описании метода "Создание рассылки".
Информация о рассылке
Пример запроса
curl -X GET https://api.msndr.net/v1/email/campaigns/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{"id":1,"from_email":"hello@world.com","from_name":null,"html":"<h1>Hello World</h1>","text":"Hello World","state":"sending","recipients_count":10,"purchase":{"enable":true,"subscribers":10,"credits":0,"deficit":0},"statistics":{"delivered":1,"bounced":0,"delivering":0,"uniq_open":0,"total_open":0,"last_open_at":nil,"uniq_click":0,"total_click":0,"last_click_at":nil,"unsubscription":0,"spam":0}}
GET /email/campaigns/:id
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
from_email | Адрес отправителя |
from_name | Имя отправителя |
html | |
text | |
state | Статус |
recipients_count | Количество получателей |
purchase | Информация о тарификации |
statistics | Статистика |
Статусы
Значение | Описание |
---|---|
draft | Черновик |
pending | На модерации |
delayed | Запланированная |
sending | Отправляется |
canceled | Отменена |
stopped | Остановлена |
completed | Завершена |
archived | В архиве |
Информация о тарификации
Атрибут | Описание |
---|---|
enable | Может принимать значение true (отправка возможна) или false (недостаточно средств) |
subscribers | Количество подписчиков которое будет списано |
credits | Количество кредитов которое будет списано |
deficit | Количество недостающих средств |
Статистика
Атрибут | Описание |
---|---|
delivered | Количество доставленных сообщений |
bounced | Количество недоставленный сообщений |
delivering | Количество доставляющихся сообщений |
uniq_open | Количество уникальных открытий |
total_open | Количество открытий всего |
lastopenat | Timestamp последнего открытия |
uniq_click | Количество уникальных переходов |
total_click | Количество переходов всего |
lastclickat | Timestamp последнего перехода |
unsubscription | Количество отписок |
spam | Количество нажатий кнопки "спам" |
Webhooks
Данный механизм позволяют получать POST запросы на указанный URL, когда происходят события, связанные с одиночными сообщениями, сообщениями по шаблонам или отправленными по SMTP сообщениями.
Структура сообщений, отправляемых на указанный URL:
{"message":{"id":1},"event":{"name":"clicked","timestamp":1539062173,"data":{"url":"https://example.com"}}}
Ключ message содержит информацию о сообщении, с которым связано событие. Ключ event содержит информацию о событии. На данный момент ключ data возвращается только для события clicked, и содержит адрес ссылки, по которой кликнули.
Виды событий
Событие | Описание |
---|---|
delivered | Сообщение доставлено |
opened | Сообщение открыто |
clicked | Получатель перешел по ссылке. Ключ event.data содержит URL ссылки |
unsubscribed | Получатель отписался |
complined | Получатель пожаловался на спам |
skipped | Сообщение не было отправлено (возможные причины: получатель ранее отписался или пожаловался на спам) |
soft_bounced | Сообщение не принято почтовым сервером получателя (возможно, будет принято позже) |
hard_bounced | Сообщение не принято почтовым сервером получателя |
Установка webhook
Пример JSON для запроса
{"url":"https://example.com/some/path"}
Пример запроса
curl -X POST https://api.msndr.net/v1/email/webhook \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример ответа в случае успеха
{"url":"https://example.com/some/path"}
POST /email/webhook
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
url | URL, на который отправлять данные о событии | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
url | URL, на который отправлять данные о событии |
Получение информации о webhook
Пример запроса
curl -X GET https://api.msndr.net/v1/email/webhook \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{"url":"https://example.com/some/path"}
GET /email/webhook
Удаление webhook
Пример JSON для запроса
{"url":"https://example.com/some/path"}
Пример запроса
curl -X DELETE https://api.msndr.net/v1/email/webhook \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
DELETE /email/webhook
SMTP
Базовый URL
Адрес:
smtp.msndr.net
Порт:
25
или
587
Использование шифрования SSL/TLS не является обязательным, его использование будет определено автоматически, в соответствии с настройками Вашего ПО. В данный момент на сервере поддерживается шифрование TLS версий 1.2 и 1.3. При использовании шифрования порт не меняется.
Аутентификация
Имя пользователя: email вашего аккаунта
Пароль: API ключ
Чтобы получить API ключ, авторизуйтесь в личном кабинете email рассылок. В разделе автоматизация перейдите во вкладку API и SMTP. Нажмите на "Параметры подключении и SMTP".
Пример SMTP сессии
$ telnet smtp.msndr.net 25
Trying 95.213.163.242...
Connected to smtp.msndr.net.
Escape character is '^]'.
220 smtp.msndr.net ESMTP service ready
ehlo sender
250-smtp.msndr.net
250-STARTTLS
250-AUTH PLAIN LOGIN
250-PIPELINING
250 8BITMIME
auth plain AHVzZXJAZXhhbXBsZS5vcmcAc29tZS1zdXBlci1wdXBlci1zZWNyZXQta2V5
235 authentication ok
mail from: mail@from.com
250 Ok
rcpt to: rcpt@to.com
250 Ok
rcpt to: rcpt1@to.com
250 Ok
data
354 End data with <CR><LF>.<CR><LF>
From: Mail From <mail@from.com>
Subject: Hello
X-Client-Id: 123
How are you doing?
.
250 Message accepted (sent messages <rcpt@to.com:1>,<rcpt1@to.com:2>)
quit
221 smtp.msndr.net closing connection
Connection closed by foreign host.
В случае отправки сообщений ответ будет содержать строку с информацией об отправленных письмах.
Строка содержит адреса получателей и ID сообщений в формате <email:id>, объединенные запятой (см. пример выше).
К отправляемому сообщению можно добавлять собственные заголовки, используя заголовки формата.
X-My-Header: my value
Так, в указанном выше примере в результирующем сообщении будет присутствовать заголовок.
Client-Id: 123