Документация Email API

Документ содержит сведения о программном интерфейсе сервиса 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.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

Способ тарификации сообщения. Возможные значения:

subscriber_priority

credit_priority

subscriber

credit

Значение по умолчанию:

subscriber_priority

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

Способ тарификации сообщения. Возможные значения:

subscriber_priority

credit_priority

subscriber

credit

Значение по умолчанию:

subscriber_priority

Нет

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

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

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

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

Элементы массива значений

Параметр Описание Обязательный
parameter_id ID параметра группы получателей Да
value Да

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

Ответ сервера содержит JSON со следующими атрибутами:

Атрибут Описание
id Идентификатор
email Адрес
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 Идентификатор
email Адрес
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

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

Параметр Описание Обязательный
email Нет
values Массив значений для параметров

Элементы массива значений

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

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

Ответ сервера содержит JSON со следующими атрибутами:

Атрибут Описание
id Идентификатор
email Адрес
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 Идентификатор
email Адрес
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. Нет

Массив получателей

Параметр Описание Обязательный
email Да
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

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

Параметр Описание Обязательный
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.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

Универсальная платформа
для быстрого достижения ваших целей

Попробовать бесплатно