Общие сведения

Данный документ содержит сведения о программном интерфейсе сервиса email рассылок (далее - «API»). Через API внешние приложения получают доступ к системе управлению списками получателей, отправке одиночных email сообщений, рассылок, а также прочий функционал для работы со списками получателей и статистикой рассылок

Базовый URL

Базовый URL для всех запросов
https://api.msndr.net/v1 Альтернативный базовый 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.ru/v1/email/lists?page_number=2&page_size=3 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'

Поддерживаемые параметры

ПараметрОписаниеpage_numberНомер запрашиваемой страницы. По умолчанию: 1page_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.

Информация о балансе

Пример запроса
curl -X GET https://api.msndr.ru/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.ru/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.ru/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_nametoДаsubjectДаtextДолжен присутствовать хотя бы один параметр:textилиhtmlhtmlДолжен присутствовать хотя бы один параметр:textилиhtmlattachmentsМассив с вложениями. Поддерживается только для запросов с типом содержимого multipart/form-datapaymentСпособ тарификации сообщения. Возможные значения:
subscriber_priority
credit_priority
subscriber
credit
Значение по умолчанию:subscriber_prioritysmtp_headersСписок заголовков, которые будут добавлены к отправляемому SMTP сообщению

Способы тарификации сообщения

ЗначениеОписаниеsubscriber_priorityТарифицируется "подписчик", если не доступны "подписчики", используется "письмо". Если нет "писем", возвращается ошибка.credit_priorityТарифицируется "письмо". Если нет "писем", используется "подписчик". Если нет "подписчиков", возвращается ошибка.subscriberТарифицируется "подписчик". Если нет "подписчиков", возвращается ошибка.creditТарифицируется "письмо". Если нет "писем", возвращается ошибка.

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:
АтрибутОписаниеidИдентификатор сообщенияfrom_emailАдрес отправителяfrom_nameИмя отправителяtoАдрес получателяsubjectТемаtextТекстовая версия сообщенияhtmlHTML версия сообщенияattachmentsМассив имен вложенных файловstatusСтатус сообщенияeventsИнформация о событиях
Статусы сообщения
СтатусОписаниеqueuedПринято в очередьsentОтправлено, ожидатся подтверждение доставкиdeliveredДоставленоskippedНе отправлено. Получатель отписался или находится в списке проблемных получателейsoft_bouncedНе доставлено. Временно отклонено принимающей сторонойhard_bouncedСообщение не может быть доставлено
Информация о событиях
СобытиеОписаниеopenСообщение прочитаноredirectПолучатель перешел по ссылкеspamСообщение помечено как спамunsubscribeПользователь отписался
Обратите внимание на то, что при отправке сообщений сервер может вернуть ответ со статусом 429. Это означает, что вы превысили количество сообщений, разрешенное к отправке, в единицу времени. Результат отправки сообщений влияет на лимит сообщений в единицу времени. Таким образом, если вы отправляете письма только вашим клиентам, только на существующие адреса, не рассылаете спам и тп, то разрешенное количество сообщений в единицу времени для вашего аккаунта будет увеличиваться, и наоборот.

Получение информации о сообщении

Пример запроса
curl -X GET https://api.msndr.ru/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Текстовая версия сообщенияhtmlHTML версия сообщения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 - идентификатор шаблона

Параметры запроса

ПараметрОписаниеОбязательныйtoemail получателяДаparamsПараметры подстановкиНетpaymentСпособ тарификации сообщения. Возможные значения:
subscriber_priority
credit_priority
subscriber
credit
Значение по умолчанию:subscriber_priorityНет
Пример запроса
curl -X POST https://api.msndr.ru/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.ru/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.ru/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.ru/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.ru/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.ru/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.ru/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.ru/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.ru/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.ru/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 - идентификатор параметра

Параметры запроса

ПараметрОписаниеОбязательныйtitlekindВозможные значения:
string
numeric
date
boolean
geo
При изменении типа параметра, соответствующие значения обнулятся

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:
АтрибутОписаниеidИдентификаторtitleНазваниеkindТип

Удаление параметра

Пример запроса
curl -X DELETE https://api.msndr.ru/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.ru/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

Параметры запроса

ПараметрОписаниеОбязательныйemailДаunconfirmedСоздать неподтвержденного получателя. Необходимо задать любое значение, например, true, t или 1. По умолчанию создается подтвержденный получательНетvaluesМассив значений для параметров
Элементы массива значений
ПараметрОписаниеОбязательныйparameter_idID параметра группы получателейДаvalueДа

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:
АтрибутОписаниеidИдентификаторemailАдресconfirmedПодтвержден получатель или нетstatusСтатус получателя. Возможные значения: active, incorrect, unconfirmed, unsubscribedvaluesМассив значений
Элементы массива значений
ПараметрОписаниеparameter_idID параметра группы получателейkindТип параметраvalueЗначение

Информация о получателе

Данный метод позволяет получить информацию о получателе по ID.
Пример запроса
curl -X GET https://api.msndr.ru/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_idID группыДаidID получателяДа

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:
АтрибутОписаниеidИдентификаторemailАдресconfirmedПодтвержден получатель или нетstatusСтатус получателя. Возможные значения: active, incorrect, unconfirmed, unsubscribedvaluesМассив значений
Элементы массива значений
ПараметрОписаниеparameter_idID параметра группы получателейkindТип параметраvalueЗначение

Обновление получателя

Пример JSON для запроса
{ "email":"alice@example.org", "values":[ { "parameter_id":"1", "value":"Alice" }, { "parameter_id":"2", "destroy":"true" } ] }
Пример запроса
curl -X PATCH https://api.msndr.ru/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

Параметры запроса

ПараметрОписаниеОбязательныйemailНетvaluesМассив значений для параметров
Элементы массива значений
ПараметрОписаниеОбязательныйparameter_idID параметра группы получателейДаvalueНе может быть одновременно использован с параметром destroyНетdestroyИспользуется для удаления значения. Для удаления значения необходимо задать любое значение, например, true, t или 1. Не можеть быть использован одновременно с параметром valueНет

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:
АтрибутОписаниеidИдентификаторemailАдресconfirmedПодтвержден получатель или нетstatusСтатус получателя. Возможные значения: active, incorrect, unconfirmed, unsubscribedvaluesМассив значений
Элементы массива значений
ПараметрОписаниеparameter_idID параметра группы получателейkindТип параметраvalueЗначение

Список получателей

Пример запроса
curl -X GET https://api.msndr.ru/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ИдентификаторemailАдресconfirmedПодтвержден получатель или нетstatusСтатус получателя. Возможные значения: active, incorrect, unconfirmed, unsubscribedvaluesМассив значений
Элементы массива значений
ПараметрОписаниеparameter_idID параметра группы получателейkindТип параметраvalueЗначение

Удаление получателя

Пример запроса
curl -X DELETE https://api.msndr.ru/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.Нет
Массив получателей
ПараметрОписаниеОбязательныйemailДаvaluesМассив значений для параметров
Элементы массива значений
ПараметрОписаниеОбязательныйparameter_idID параметра группы получателейДа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.ru/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.ru/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

Параметры запроса

ПараметрОписаниеОбязательныйemailИскомый адресДа

Ответ сервера

Ответ сервера содержит коллекцию получателей в группе. Каждый элемент содержит следующие атрибуты:
АтрибутОписаниеemailАдрес получателя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.ru/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.ru/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.ru/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.ru/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.ru/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.ru/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

Параметры запроса

ПараметрОписаниеОбязательныйnameaddresscountrycityphonezip

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:
АтрибутОписаниеidИдентификаторnameНазваниеaddressАдресcountryСтранаcityГородphoneТелефонzipПочтовый индексcurrentЯвляется ли организацией по умолчанию

Удаление организации

Пример запроса
curl -X DELETE https://api.msndr.ru/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.ru/v1/email/campaigns \
     -H 'Content-Type: application/json'              \
     -H 'Authorization: Bearer $API_TOKEN'            \
     -d '...JSON...'
Пример запроса для создания рассылки с вложениями
curl -X POST https://api.msndr.ru/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_nametexthtmlДаlistsМассив групп получателейДа
Элементы массива групп получателей
ПараметрОписаниеОбязательныйidID группы получателейДа

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:
АтрибутОписаниеidИдентификаторfrom_emailАдрес отправителяfrom_nameИмя отправителяhtmltextstateСтатус (рассылка создается в статусе 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Количество открытий всегоlastopenatTimestamp последнего открытияuniq_clickКоличество уникальных переходовtotal_clickКоличество переходов всегоlastclickatTimestamp последнего переходаunsubscriptionКоличество отписокspamКоличество нажатий кнопки "спам"

Отправка рассылки

Пример запроса
curl -X PATCH https://api.msndr.ru/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

Параметры запроса

ПараметрОписаниеОбязательныйidID созданной рассылкиДа

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:
АтрибутОписаниеidИдентификаторfrom_emailАдрес отправителяfrom_nameИмя отправителяhtmltextstateСтатус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Количество открытий всегоlastopenatTimestamp последнего открытияuniq_clickКоличество уникальных переходовtotal_clickКоличество переходов всегоlastclickatTimestamp последнего переходаunsubscriptionКоличество отписокspamКоличество нажатий кнопки "спам"

Список рассылок

Пример запроса
curl -X GET https://api.msndr.ru/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.ru/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Имя отправителяhtmltextstateСтатус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Количество открытий всегоlastopenatTimestamp последнего открытияuniq_clickКоличество уникальных переходовtotal_clickКоличество переходов всегоlastclickatTimestamp последнего перехода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.ru/v1/email/webhook \
     -H 'Content-Type: application/json'       \
     -H 'Authorization: Bearer $API_TOKEN'     \
     -d '...JSON...'
Пример ответа в случае успеха
{
  "url":"https://example.com/some/path"
}
POST /email/webhook

Параметры запроса

ПараметрОписаниеОбязательныйurlURL, на который отправлять данные о событииДа

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:
АтрибутОписаниеurlURL, на который отправлять данные о событии

Получение информации о webhook

Пример запроса
curl -X GET https://api.msndr.ru/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.ru/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.