Данный документ содержит сведения о программном интерфейсе сервиса email рассылок (далее - «API»). Через API внешние приложения получают доступ к системе управлению списками получателей, отправке одиночных email сообщений, рассылок, а также прочий функционал для работы со списками получателей и статистикой рассылок
Базовый URL для всех запросов
Альтернативный базовый URL для всех запросов
https://api-reserve.msndr.net/v1
Используйте альтернативный URL в случае, когда ваш IP заблокирован или имеет ограничения со стороны РКН.
Для удостоверения подлинности запросов, в каждом обращении к API необходимо отправлять заголовок содержащий Ваш ключ.
Authorization: Bearer $API_TOKEN
Ключ для доступа к API можно получить в личном кабинете.
Держите Ваш ключ для доступа к API в секрете.
Для обмена данными используется формат JSON, поэтому, в каждом запросе должен присутствовать заголовок
Content-Type: application/json
Все данные от сервера возвращаются так же, в формате JSON.
Списки данных (Collection) - постраничный способ выдачи данных, используемый в некоторых методах. Для управления страницами выдачи списка данных в заголовках запроса необходимо передавать параметры pagenumber и pagesize:
Пример запроса
curl -X GET https://api.mailopost.ru/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":8,
"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.mailopost.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 | Сумма на балансе |
Пример 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.mailopost.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.mailopost.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_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.mailopost.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 | Текстовая версия сообщения |
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.mailopost.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.mailopost.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.mailopost.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.mailopost.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.mailopost.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.mailopost.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.mailopost.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.mailopost.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.mailopost.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.mailopost.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 - идентификатор параметра
Параметр | Описание | Обязательный |
---|---|---|
title | ||
kind | Возможные значения:string numeric date boolean geo При изменении типа параметра, соответствующие значения обнулятся |
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
title | Название |
kind | Тип |
Пример запроса
curl -X DELETE https://api.mailopost.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.mailopost.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
Параметр | Описание | Обязательный |
---|---|---|
Да | ||
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.mailopost.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_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.mailopost.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
Параметр | Описание | Обязательный |
---|---|---|
Нет | ||
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.mailopost.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 | Идентификатор |
Адрес | |
confirmed | Подтвержден получатель или нет |
status | Статус получателя. Возможные значения: active, incorrect, unconfirmed, unsubscribed |
values | Массив значений |
Элементы массива значений
Параметр | Описание |
---|---|
parameter_id | ID параметра группы получателей |
kind | Тип параметра |
value | Значение |
Пример запроса
curl -X DELETE https://api.mailopost.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. | Нет |
Массив получателей
Параметр | Описание | Обязательный |
---|---|---|
Да | ||
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.mailopost.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.mailopost.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
Параметр | Описание | Обязательный |
---|---|---|
Искомый адрес | Да |
Ответ сервера содержит коллекцию получателей в группе. Каждый элемент содержит следующие атрибуты:
Атрибут | Описание |
---|---|
Адрес получателя | |
recipients | Массив, содержащий информацию о списках, в которых есть искомый получатель |
Пример JSON для запроса
{
"name":"My Organization",
"address":"Lenina 40",
"country":"Russia",
"city":"Tomsk",
"phone":"+7-3822-123-456",
"zip":"634000"
}
Пример запроса
curl -X POST https://api.mailopost.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.mailopost.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.mailopost.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.mailopost.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.mailopost.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.mailopost.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
Параметр | Описание | Обязательный |
---|---|---|
name | ||
address | ||
country | ||
city | ||
phone | ||
zip |
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Пример запроса
curl -X DELETE https://api.mailopost.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.mailopost.ru/v1/email/campaigns \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Пример запроса для создания рассылки с вложениями
curl -X POST https://api.mailopost.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_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.mailopost.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
Параметр | Описание | Обязательный |
---|---|---|
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.mailopost.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.mailopost.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 | Имя отправителя |
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 | Количество нажатий кнопки "спам" |
Данный механизм позволяют получать 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 | Сообщение не принято почтовым сервером получателя |
Пример JSON для запроса
{
"url":"https://example.com/some/path"
}
Пример запроса
curl -X POST https://api.mailopost.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
Параметр | Описание | Обязательный |
---|---|---|
url | URL, на который отправлять данные о событии | Да |
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
url | URL, на который отправлять данные о событии |
Пример запроса
curl -X GET https://api.mailopost.ru/v1/email/webhook \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{
"url":"https://example.com/some/path"
}
GET /email/webhook
Пример JSON для запроса
{
"url":"https://example.com/some/path"
}
Пример запроса
curl -X DELETE https://api.mailopost.ru/v1/email/webhook \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
DELETE /email/webhook
Адрес: 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
.
У нас уже есть готовые интеграции с различными сервисами. Доступна интеграция с Tilda, LPgenerator и еще десятками популярных сервисов через онлайн-коннектор ApiX-Drive.