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

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

Базовый URL

Базовый URL для всех запросов

https://api.mailopost.ru/v1

Альтернативный базовый URL для всех запросов

https://api-reserve.msndr.net/v1

Используйте альтернативный URL в случае, когда ваш IP заблокирован или имеет ограничения со стороны РКН.

Аутентификация

Для удостоверения подлинности запросов, в каждом обращении к API необходимо отправлять заголовок содержащий Ваш ключ.

Authorization: Bearer $API_TOKEN

Ключ для доступа к API можно получить в личном кабинете в разделе Автоматизация => API и SMTP => Параметры подключения API и SMTP

Держите Ваш ключ для доступа к API в секрете.

Формат обмена данных

Для обмена данными используется формат JSON, поэтому, в каждом запросе должен присутствовать заголовок

Content-Type: application/json

Все данные от сервера возвращаются так же, в формате JSON.

Получение списков данных (Collection)

Списки данных (Collection) - постраничный способ выдачи данных, используемый в некоторых методах. Для управления страницами выдачи списка данных в заголовках запроса необходимо передавать параметры page_number и page_size:

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

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	Ресурс не найден
409	Действие недопустимо в текущем состоянии ресурса
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	Доступное количество подписчиков
tariff.credits	Количество писем
tariff.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.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
  }
}

Пример запроса для отправки сообщения с вложениями

Вложения могут быть документами и медиа файлами. Суммарный размер вложений не должен превышать 5 Мбайт.

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	Email отправителя	Да
from_name	Имя отправителя	Нет
to	Email получателя	Да
subject	Тема письма	Да
text	Текстовая версия письма	Должен присутствовать хотя бы один параметр: text или html
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	Пользователь отписался

Отправка по шаблону

Используйте интерфейс конструктора писем, чтобы составить макет письма в своем личном кабинете, а управлять его отправкой из своего приложения при помощи API. Указывайте параметры, чтобы персонализировать отправляемые email. При отправке параметры будут заменены на тексты из API запроса. Вносите корректировки в дизайн макета письма в личном кабинете, при этом оставляя без изменений код отправки писем. В личном кабинете в разделе "Автоматизация", выберите "Одиночное по шаблону" и создайте шаблон письма. Отправляйте письма по этому шаблону с параметрами. Для подстановки параметра в шаблоне используйте конструкцию [%имя параметра%], например [%name%], [%age%] и т.д.

Создание шаблонa

Вы можете создать шаблон письма, используя этот метод, или зайти в свой личный кабинет и создать новый шаблон в конструкторе писем в разделе «автоматизация» => «Одиночные по шаблону».

Пример JSON для запроса

{
  "from_email": "hello@world.com",
  "subject": "Hello World",
  "text": "Hello World",
  "html": "<h1>Hello World</h1>"
  "preset_params": [
    "name",
    "age"
  ]
}

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

curl -X POST https://api.mailopost.ru/v1/email/templates \
     -H 'Content-Type: application/json'              \
     -H 'Authorization: Bearer $API_TOKEN'            \
     -d '...JSON...'

Пример ответа в случае успеха

{
  "id": 1,
  "from_email": "hello@world.com",
  "from_name": null,
  "subject": "Hello World",
  "html": true,
  "text": true,
  "state": "draft"
  "preset_params": [
    "name",
    "age"
  ]
}

POST /email/templates

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

Параметр	Описание	Обязательный
from_email	Адрес отправителя	Да
from_name	Имя отправителя
subject	Тема письма	Да
name	Название шаблона
text
html		Да
preset_params	Массив параметров для подстановки в шаблон

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

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

Атрибут	Описание
id	Идентификатор
from_email	Адрес отправителя
from_name	Имя отправителя
subject	Тема письма
name	Название шаблона
html
text
state	Статус (создается в статусе draft)
preset_params	Массив параметров для подстановки в шаблон

Статусы

Значение	Описание
draft	Черновик
pending	На модерации
active	Модерация пройдена
inactive	Пауза
canceled	Отменена

Получение списка шаблонов

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

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

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

curl -X GET https://api.mailopost.ru/v1/email/templates/1 \
     -H 'Content-Type: application/json'    \
     -H 'Authorization: Bearer $API_TOKEN'

Пример ответа в случае успеха

{
  "id": 1,
  "name": null,
  "subject": "Hello world!",
  "from_email": "hello@world.com",
  "from_name": "Mr.Hello",
  "state": "active",
  "preset_params": [
      "age",
      "name"
  ],
  "html": true,
  "text": true
}

GET /email/templates/:template_id

где: template_id - идентификатор шаблона

Изменение шаблона

Меняются только переданные поля.

Пример JSON для запроса

{
  "subject": "Hello again",
  "html": "<h1>Hello again, [%name%]</h1>"
}

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

curl -X PATCH https://api.mailopost.ru/v1/email/templates/1 \
     -H 'Content-Type: application/json'    \
     -H 'Authorization: Bearer $API_TOKEN'  \
     -d '...JSON...'

Пример ответа в случае успеха

{
  "id": 1,
  "name": "Hello World",
  "subject": "Hello again",
  "from_email": "hello@world.com",
  "from_name": null,
  "state": "pending",
  "preset_params": [
      "age",
      "name"
  ],
  "html": true,
  "text": true
}

PATCH /email/templates/:template_id

где: template_id - идентификатор шаблона

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

Параметр	Описание
from_email	Адрес отправителя
from_name	Имя отправителя
subject	Тема письма
name	Название шаблона
text	Текстовая версия
html	HTML-версия
preset_params	Массив параметров для подстановки в шаблон (заменяет прежний)
attachments	Вложения, только в multipart/form-data; переданные вложения заменяют прежние

Статус после изменения

Изменение письма (html, text, тема, отправитель, вложения) активного шаблона:

• если аккаунт доверенный — шаблон остаётся в статусе active, письма уходят уже по новому шаблону;
• иначе шаблон уходит на модерацию (pending), и до её прохождения письма по нему не отправляются.

Изменение шаблона в статусе pending, draft, inactive или canceled, а также только названия или параметров для подстановки статус не меняет. Шаблон в процессе удаления изменить нельзя (ошибка 400).

Отправка шаблона на модерацию

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

curl -X PATCH https://api.mailopost.ru/v1/email/templates/1/to_pending \
     -H 'Content-Type: application/json'    \
     -H 'Authorization: Bearer $API_TOKEN'

Пример ответа в случае успеха

{
  "id": 1,
  "name": "Hello World",
  "subject": "Hello World",
  "from_email": "hello@world.com",
  "from_name": null,
  "state": "pending",
  "preset_params": [
      "age",
      "name"
  ],
  "html": true,
  "text": true
}

PATCH /email/templates/:template_id/to_pending

Отправка одиночного сообщения по шаблону

Пример JSON для запроса

{
  "to": "bob@example.org",
  "payment": "credit",
  "params": {
    "name": "Ivan",
    "age": "33"
  }
}

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

Параметр	Описание	Обязательный
to	email получателя	Да
params	Параметры подстановки	Нет
payment	Способ тарификации сообщения. Возможные значения: subscriber_priority credit_priority subscriber credit Значение по умолчанию: subscriber_priority	Нет

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

curl -X POST https://api.mailopost.ru/v1/email/templates/:template_id/messages \
     -H 'Content-Type: application/json'        \
     -H 'Authorization: Bearer $API_TOKEN'      \
     -d '...JSON...'

Пример запроса для отправки сообщения с вложениями

Вложения могут быть документами и медиа файлами. Суммарный размер вложений не должен превышать 5 Мбайт.

curl -X POST https://api.mailopost.ru/v1/email/templates/:template_id/messages \
     -H 'Authorization: Bearer $API_TOKEN'      \
     -F to=to@example.com                       \
     -F params[name]=Ivan                       \
     -F attachments[]=@/path/to/file1           \
     -F attachments[]=@/path/to/file2

POST /email/templates/:template_id/messages

где: template_id - идентификатор шаблона

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

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

Атрибут	Описание
id	Идентификатор сообщения
to	Адрес получателя
status	Статус сообщения
events	Информация о событиях

Статусы сообщения

Статус	Описание
queued	Принято в очередь
sent	Отправлено, ожидается подтверждение доставки
delivered	Доставлено
skipped	Не отправлено. Получатель отписался или находится в списке проблемных получателей
soft_bounced	Не доставлено. Временно отклонено принимающей стороной
hard_bounced	Сообщение не может быть доставлено

Информация о событиях

Событие	Описание
open	Сообщение прочитано
redirect	Получатель перешел по ссылке
spam	Сообщение помечено как спам
unsubscribe	Пользователь отписался

Обратите внимание, что при отправке сообщений сервер может вернуть ответ со статусом 429. Это означает, что вы превысили количество сообщений, разрешенное к отправке, в единицу времени. Результат отправки сообщений влияет на лимит сообщений в единицу времени. Количество сообщений разрешенных к отрпавке может уменьшаться, если среди получателей ваших писем много несуществующих email адресов и жалоб. Если вы считаете что получили ответ 429 по ошибке, обратитесь в службу технической поддержки.

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

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

Группы получателей

Создание группы

Пример 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

где :id - идентификатор группы в которой создается параметр

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

Параметр	Описание	Обязательный
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 - идентификатор группы для получения списка параметров

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

Ответ сервера содержит коллекцию параметров группы получателей. Каждый элемент содержит следующие атрибуты:

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

Получатели

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

Метод создает получателя в группе получателей. При создании нового получателя вы можете прикреплять дополнительную информацию в виде тегов или параметров получателя. Параметры имеют название и значения, которые присоединены к получателю в рамках группы. Теги — это дополнительная информация (метка) получателя, которая прикреплена в рамках аккаунта и доступна во всех группах где будет создан получатель с аналогичным email

Вы можете использовать Параметры и Теги для персонализации макета письма и фильтрации при создании рассылок из личного кабинета.

Пример JSON для запроса

{
  "email":"alice@example.org",
  "unconfirmed": true,
  "values":[
    {
      "parameter_id":"1",
      "value":"Alice"
    },
    {
      "parameter_id":"2",
      "value":"22"
    }
  ],
  "tags":[
    "buyer",
    "regular customer"
  ]
}

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

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
    }
  ],
  "tags":[
    "buyer",
    "regular customer"
  ]
}

POST /email/lists/:id/recipients

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

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

Элементы массива значений с параметрами получателя

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

Элементы массива значений с тегами получателя*

Массив значений тегов состоит из обычного массива. Например, ['tag1', 'tag2']

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

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

Атрибут	Описание
id	Идентификатор
email	Адрес
confirmed	Подтвержден получатель или нет
status	Статус получателя. Возможные значения: active, incorrect, unconfirmed, unsubscribed
values	Массив значений параметров
tags	Массив значений тегов

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

Параметр	Описание
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
    }
  ],
  "tags":[
    "buyer",
    "regular customer"
  ]
}

GET /email/lists/:list_id/recipients/:id

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

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

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

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

Атрибут	Описание
id	Идентификатор
email	Адрес
confirmed	Подтвержден получатель или нет
status	Статус получателя. Возможные значения: active, incorrect, unconfirmed, unsubscribed
values	Массив значений
tags	Массив значений тегов

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

Параметр	Описание
parameter_id	ID параметра группы получателей
kind	Тип параметра
value	Значение

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

Этот метод позволяет обновить параметры и теги получателя

Пример JSON для запроса

{
  "email":"alice@example.org",
  "values":[
    {
      "parameter_id":"1",
      "value":"Alice"
    },
    {
      "parameter_id":"2",
      "destroy":"true"
    }
  ],
  "tags":[
    {
      "value":"buyer"
    },
    {
      "value":"customer",
      "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
    }
  ],
  "tags":[
    "buyer",
    "regular customer"
  ]
}

PATCH /email/lists/:list_id/recipients/:id

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

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

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

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

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

tags состоит из массива значений [ 'tag1', 'tag2', 'tag3' ]

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

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

Атрибут	Описание
id	Идентификатор
email	Адрес
confirmed	Подтвержден получатель или нет
status	Статус получателя. Возможные значения: active, incorrect, unconfirmed, unsubscribed
values	Массив значений
tags	Массив значений тегов

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

Параметр	Описание
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
        }
      ],
      "tags":[
        "buyer",
        "regular customer"
      ]
    },
    {
      "id":2,
      "email":"bob@example.org",
      "confirmed":true,
      "status": "active",
      "list_id":1,
      "values":[
      ],
      "tags":[
      ]
    }
  ]
}

GET /email/lists/:id/recipients

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

Ответ сервера содержит коллекцию получателей группы. Каждый элемент содержит следующие атрибуты:

Атрибут	Описание
id	Идентификатор получателя
email	Email получателя
confirmed	Подтвержден получатель или нет
status	Статус получателя. Возможные значения: active, incorrect, unconfirmed, unsubscribed
values	Массив значений параметра получателей
tags	Массив значений тегов

Элементы массива значений 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	Запустить связанные триггеры. Возможные значения: trigger_any trigger_fresh	Нет
tags	Массив значений тегов	Нет
callback_url	url, на который будет отправлен запрос после завершения импорта	Нет

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

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

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

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

Параметр run_triggers

Значение	Описание
trigger_any	Запустить связанные триггеры для всех получателей
trigger_fresh	Запустить связанные триггеры только для новых получателей

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

Параметр	Описание
id	Идентификатор импорта. В дальнейшем может использоваться для получения информации о ходе импорта
status	Статус импорта
callback_url	url, на который будет отправлен запрос после окончания импорта

Пример 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"
        }
      ]
    }
  ],
  "tags":[
    "buyer",
    "regular customer"
  ]
}

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

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",
  "callback_url": null
}

Пример запроса после окончания импорта, если указан callback url

{
  "id":7,
  "status":"completed",
  "callback_url":"https://my-callback-url.com/some-secret"
}

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

Метод осуществляет поиск получателя по 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

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

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

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

Ответ сервера содержит коллекцию получателей в группе. Каждый элемент содержит следующие атрибуты:

Атрибут	Описание
email	Email получателя
recipients	Массив, содержащий информацию о списках, в которых найден получатель

Сегменты

Список сегментов

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

curl -X GET https://api.mailopost.ru/v1/email/segments \
     -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,
       "title" : "Segment Number One"
     }
  ]
}

GET /email/segments

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

Ответ сервера содержит коллекцию сегментов. Каждый элемент содержит следующие атрибуты:

Атрибут	Описание
id	Идентификатор сегмента
title	Название сегмента

Организации

Создание организации

Пример 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	Email отправителя	Да
subject	Тема письма в рассылке	Да
from_name	Имя отправителя	Нет
text	Текстовая версия письма	Нет
html	HTML версия письма	Да
segment_id	ID сегмента	Один из параметров segment_id или lists должен присутствовать
lists	Массив групп получателей	Один из параметров segment_id или lists должен присутствовать

Элементы массива групп получателей

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

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

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

Атрибут	Описание
id	Идентификатор созданной рассылки
from_email	Адрес отправителя
from_name	Имя отправителя
html	HTML версия письма
text	Текстовая версия письма
state	Статус (рассылка создается в статусе draft)
recipients_count	Количество получателей в рассылке
purchase	Информация о тарификации
statistics	Статистика рассылки

Статусы рассылки

Значение	Описание
draft	Черновик
pending	На модерации
delayed	Запланированная
sending	Отправляется
canceled	Отменена
stopping	Останавливается
stopped	Остановлена
completed	Завершена
archived	В архиве

Информация о тарификации

Атрибут	Описание
enable	Может принимать значение true (отправка возможна) или false (необходимо улучшить тариф)
subscribers	Количество подписчиков которое будет списано из тарифа
credits	Количество писем которое будет списано из тарифа
deficit	Число на которое необходимо увеличить количество подписчиков или писем в тарифе

Статистика

Атрибут	Описание
delivered	Количество доставленных сообщений
bounced	Количество недоставленный сообщений
delivering	Количество доставляющихся сообщений
uniq_open	Количество уникальных открытий
total_open	Количество открытий всего
last_open_at	Timestamp последнего открытия
uniq_click	Количество уникальных переходов
total_click	Количество переходов всего
last_click_at	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'                  \
     -d '...JSON...'

Пример ответа в случае успеха

{
  "id":1,
  "from_email":"hello@world.com",
  "from_name":null,
  "html":"<h1>Hello World</h1>",
  "text":"Hello World",
  "state":"sending",
  "time_zone":"Fiji",
  "start_at":"30.10.2022 01:00 UTC",
  "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

Отправка отложенной рассылки

Метод позволяет отправить рассылку в заданное время, которая ранее была создана с помощью метода Создание рассылки

Пример JSON для запроса

{
  "start_at": "30.10.2022 13:00",
  "time_zone": "Fiji",
}

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

curl -X PATCH https://api.mailopost.ru/v1/email/campaigns/1/schedule \
     -H 'Content-Type: application/json'                     \
     -H 'Authorization: Bearer $API_TOKEN'                   \
     -d '...JSON...'

Пример ответа в случае успеха

{
  "id":1,
  "from_email":"hello@world.com",
  "from_name":null,
  "html":"<h1>Hello World</h1>",
  "text":"Hello World",
  "state":"sending",
  "time_zone":"Fiji",
  "start_at":"30.10.2022 01:00 UTC",
  "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/schedule

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

Параметр	Описание	Обязательный
id	ID созданной рассылки	Да
start_at	Дата и время отправки	Нет
time_zone	Часовой пояс	Нет

Список часовых поясов

Название	UTC
International Date Line West	-12:00
American Samoa	-11:00
Hawaii	-10:00
Alaska	-09:00
Tijuana	-08:00
Arizona	-07:00
Saskatchewan	-06:00
Lima	-05:00
Santiago	-04:00
Brasilia	-03:00
Mid-Atlantic	-02:00
Azores	-01:00
UTC	+00:00
Paris	+01:00
Kaliningrad	+02:00
Moscow	+03:00
Tehran	+03:30
Samara	+04:00
Kabul	+04:30
Ekaterinburg	+05:00
Mumbai	+05:30
Kathmandu	+05:45
Almaty	+06:00
Rangoon	+06:30
Bangkok	+07:00
Hong Kong	+08:00
Osaka	+09:00
Adelaide	+09:30
Sydney	+10:00
Magadan	+11:00
Fiji	+12:00
Chatham Is.	+12:45
Samoa	+13:00

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

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

Атрибут	Описание
id	Идентификатор
from_email	Адрес отправителя
from_name	Имя отправителя
start_at	Дата и время отправки
time_zone	Часовой пояс
html	HTML версия письма
text	Текстовая версия письма
state	Статус
recipients_count	Количество получателей
purchase	Информация о тарификации
statistics	Статистика

Статусы

Значение	Описание
draft	Черновик
pending	На модерации
delayed	Запланированная
sending	Отправляется
canceled	Отменена
stopping	Останавливается
stopped	Остановлена
completed	Завершена
archived	В архиве

Информация о тарификации

Атрибут	Описание
enable	Может принимать значение true (отправка возможна) или false (необходимо улучшить тариф)
subscribers	Количество подписчиков которое будет списано из тарифа
credits	Количество писем которое будет списано из тарифа
deficit	Число на которое необходимо увеличить количество подписчиков или писем в тарифе

Статистика

Атрибут	Описание
delivered	Количество доставленных сообщений
bounced	Количество недоставленный сообщений
delivering	Количество доставляющихся сообщений
uniq_open	Количество уникальных открытий
total_open	Количество открытий всего
last_open_at	Timestamp последнего открытия
uniq_click	Количество уникальных переходов
total_click	Количество переходов всего
last_click_at	Timestamp последнего перехода
unsubscription	Количество отписок
spam	Количество нажатий кнопки "спам"

Отмена рассылки

Метод отменяет отправку рассылки — так же, как кнопки в личном кабинете:

• рассылка на модерации (pending) или запланированная (delayed) возвращается в черновик (draft), письма не отправляются, дата отправки сбрасывается;
• рассылка в процессе отправки (sending) останавливается (stopping, затем stopped): уже отправленные письма не отзываются, остальные не уходят. Продолжить её можно в личном кабинете.

Черновик, завершённую, уже остановленную или отменённую рассылку отменить нельзя — сервер вернёт код 409.

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

curl -X PATCH https://api.mailopost.ru/v1/email/campaigns/1/cancel \
     -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":"draft",
  "time_zone":null,
  "start_at":null,
  "recipients_count":10,
  "purchase":{
    "enable":true,
    "subscribers":10,
    "credits":0,
    "deficit":0
  },
  "statistics":{ ... }
}

Пример ответа, если рассылку отменить нельзя

{
  "errors":[
    {
      "code":409,
      "detail":"Campaign in state completed cannot be cancelled"
    }
  ]
}

PATCH /email/campaigns/:id/cancel

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

Ответ сервера содержит JSON рассылки с теми же атрибутами, что и в методе Отправка отложенной рассылки. Атрибут state — новый статус: draft (вернулась в черновик) или stopping (останавливается).

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

Метод позволяет получить весь список рассылок аккаунта.

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

curl -X GET https://api.mailopost.ru/v1/email/campaigns?statistic=false \
     -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

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

Ответ сервера содержит коллекцию рассылок. Подробнее об элементах коллекции в описании метода "Создание рассылки".

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

Параметр	Описание
statistic	Включать блок statistics в выдачу. Возможные значения: true, false. По умолчанию true. Выключение статистики существенно ускоряет работу метода.

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

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

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	HTML версия письма
text	Текстовая версия письма
state	Статус
recipients_count	Количество получателей
purchase	Информация о тарификации
statistics	Статистика рассылки

Статусы рассылки

Значение	Описание
draft	Черновик
pending	На модерации
delayed	Запланированная
sending	Отправляется
canceled	Отменена
stopping	Останавливается
stopped	Остановлена
completed	Завершена
archived	В архиве

Информация о тарификации

Атрибут	Описание
enable	Может принимать значение true (отправка возможна) или false (необходимо улучшить тариф)
subscribers	Количество подписчиков которое будет списано из тарифа
credits	Количество писем которое будет списано из тарифа
deficit	Число на которое необходимо увеличить количество подписчиков или писем в тарифе

Статистика

Атрибут	Описание
delivered	Количество доставленных сообщений
bounced	Количество недоставленный сообщений
delivering	Количество доставляющихся сообщений
uniq_open	Количество уникальных открытий
total_open	Количество открытий всего
last_open_at	Timestamp последнего открытия
uniq_click	Количество уникальных переходов
total_click	Количество переходов всего
last_click_at	Timestamp последнего перехода
unsubscription	Количество отписок
spam	Количество нажатий кнопки "спам"

Webhooks

Вы можете управлять вебхуками в кабинете сервиса, в разделе Автоматизация -> Webhooks, либо используя API описанный в этом разделе.

Механизм вебхуков позволяет получать POST запросы на указанный URL, о событиях, связанных с отправленными сообщениями. Вебхуки приходят раз в 10 минут группами не более 500 событий в одном запросе. Вы можете настроить типы сообщений, а также события, о которых хотите получать уведомления. Доступные типы сообщений: API/SMTP, рассылки, триггеры, одиночные по шаблону. Доступные события: Доставлено, Не доставлено, Пропущено, Открытие, Переход, Жалоба, Отписка.

Пример данных из полученного POST запроса:

{
"meta": {
  "type": "campaign",
  "id": 1,
  "name": "Рассылка постоянным клиентам"
},
"events": [
    {
      "id": 1164,
      "name": "delivered",
      "email": "example@gmail.com",
      "timestamp": 1684400000
    }
]

Каждый запрос содержит параметры meta и events. Параметр meta это хеш который содержит информацию о том к чему относятся события из данного запроса.

Поля параметра meta

Поле	Пример	Значения	Обязательно	Описание
type	campaign	campaign - обычная рассылка, campaign_transactional - одиночные по шаблону, campaign_workflow - триггерная рассылка, api - API или SMTP трафик	Да	Объект, с которым связаны пришедшие в вебхук события
id	1	число	Да для всех типов кроме api	ID рассылки
name	Рассылка постоянным клиентам	строка	Да для всех типов кроме api	Название рассылки

Параметр events это массив событий связанных с meta

Поля элемента массива events

Поле	Пример	Значения	Обязательно	Описание
id	1164		Да	id сообщения
name	delivered	delivered - доставлено, skipped - пропущено (при отправке на отписанных), soft_bounced - не доставлено, hard_bounced - не доставлено, opened - открытие, unsubscribed - отписка, complained - жалоба, clicked - переход по ссылке	Да	Название события
email	example@gmail.com		Да	Email адрес
timestamp	1684400000		Да	Время события
url	https://ya.ru		Да для clicked	Ссылка
user_agent	Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36		Да для clicked	Информация о браузере
ip	1.1.1.1		Да для clicked	Ip адрес
browser	Chrome		Да для clicked	Браузер
os	Windows		Да для clicked	Операционная система
device_type	Desktop		Да для clicked	Тип устройства
country	Russian Federation		Да для clicked	Страна
region	46		Да для clicked	Код региона
city	Saransk		Да для clicked	Город
delivery_status	5.1.1		Да для недоставленных	Код ответа
delivery_response	Invalid mailbox		Да для недоставленных	Текст ответа

Пример для рассылки, в которой одно доставленное сообщение, открытие, переход и отписка.

{
  "meta": {
      "id": 1,
      "name": "Рассылка постоянным клиентам",
      "type": "campaign"
    },
  "events": [
    {
      "id": 1170,
      "name": "delivered",
      "email": "example@gmail.com",
      "timestamp": 1684400000
    },
    {
      "id": 1171,
      "name": "opened",
      "email": "example@gmail.com",
      "timestamp": 1684401111
    },
    {
      "id": 1172,
      "name": "clicked",
      "email": "example@gmail.com",
      "timestamp": 1684402222,
      "url": "https://ya.ru",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36",
      "ip": "1.1.1.1",
      "browser": "Chrome",
      "os": "Windows",
      "device_type": "Desktop",
      "country": "Russian Federation",
      "region": "46",
      "city": "Saransk"
    },
    {
      "id": 1173,
      "name": "unsubscribed",
      "email": "example@gmail.com",
      "timestamp": 1684403333
    }
  ]
}

Создание вебхука

Пример JSON для запроса

{
    "title": "Api delivered webhooks",
    "url": "https://mysite.org/webhook",
    "kinds": ["api"],
    "events": ["delivered"]
}

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

curl -X POST https://api.mailopost.ru/v1/email/messages_webhooks \
     -H 'Content-Type: application/json'             \
     -H 'Authorization: Bearer $API_TOKEN'           \
     -d '...JSON...'

Пример ответа в случае успеха

{
    "id": 1,
    "url": "https://mysite.org/webhook",
    "events": [
        "delivered"
    ],
    "kinds": [
        "api"
    ],
    "status": "active",
    "title": "Api delivered webhooks"
}

POST /email/messages_webhooks

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

Параметр	Описание	Обязательный
title	Название	Да
url	Url для отправки webhooks	Да
kinds	Типы сообщений	Да
events	Список событий	Да

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

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

Атрибут	Описание
id	Идентификатор
title	Название
url	Url для отправки webhooks
kinds	Типы сообщений
events	Список событий
status	Статус

Список вебхуков

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

curl -X GET https://api.mailopost.ru/v1/email/messages_webhooks \
     -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,
            "url": "https://mysite.org/webhook",
            "events": [
                "delivered"
            ],
            "kinds": [
                "api"
            ],
            "status": "active",
            "title": "Api delivered webhooks"
        }
    ]
}

GET /email/messages_webhooks

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

Ответ сервера содержит коллекцию вебхуков. Каждый элемент содержит следующие атрибуты:

Атрибут	Описание
id	Идентификатор
title	Название
url	Url для отправки webhooks
kinds	Типы сообщений
events	Список событий
status	Статус

Информация о вебхуке

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

curl -X GET https://api.mailopost.ru/v1/email/messages_webhooks/1 \
     -H 'Content-Type: application/json'              \
     -H 'Authorization: Bearer $API_TOKEN'

Пример ответа в случае успеха

{
    "id": 1,
    "title": "Api delivered webhooks",
    "url": "https://mysite.org/webhook",
    "events": [
        "delivered"
    ],
    "kinds": [
        "api"
    ],
    "status": "active"
}

GET /email/messages_webhooks/:id

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

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

Атрибут	Описание
id	Идентификатор
title	Название
url	Url для отправки webhooks
kinds	Типы сообщений
events	Список событий
status	Статус

Изменение вебхука

Пример JSON для запроса

{
    "events": ["opened"],
    "kinds": ["campaign"],
    "status": "inactive"
}

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

curl -X PATCH https://api.mailopost.ru/v1/email/messages_webhooks/1 \
     -H 'Content-Type: application/json'                \
     -H 'Authorization: Bearer $API_TOKEN'              \
     -d '...JSON...'

Пример ответа в случае успеха

{
    "id": 1,
    "title": "Api delivered webhooks",
    "url": "https://mysite.org/webhook",
    "events": [
        "opened"
    ],
    "kinds": [
        "campaign"
    ],
    "status": "inactive"
}

PATCH /email/messages_webhooks/:id

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

Атрибут	Описание
title	Название
url	Url для отправки webhooks
kinds	Типы сообщений
events	Список событий
status	Статус

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

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

Атрибут	Описание
id	Идентификатор
title	Название
url	Url для отправки webhooks
kinds	Типы сообщений
events	Список событий
status	Статус

Удаление вебхука

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

curl -X DELETE https://api.mailopost.ru/v1/email/messages_webhooks/1 \
     -H 'Content-Type: application/json'                 \
     -H 'Authorization: Bearer $API_TOKEN'

Пример ответа в случае успеха

{
    "id": 1,
    "title": "Api delivered webhooks",
    "url": "https://mysite.org/webhook",
    "events": [
        "opened"
    ],
    "kinds": [
        "campaign"
    ],
    "status": "inactive"
}

DELETE /email/messages_webhooks/:id

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

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

Атрибут	Описание
id	Идентификатор
title	Название
url	Url для отправки webhooks
kinds	Типы сообщений
events	Список событий
status	Статус

Запрос доступных типов сообщений

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

curl -X GET https://api.mailopost.ru/v1/email/messages_webhooks/kinds \
     -H 'Content-Type: application/json'              \
     -H 'Authorization: Bearer $API_TOKEN'

Пример ответа в случае успеха

{
    "kinds": [
        "campaign",
        "campaign_transactional",
        "campaign_workflow",
        "api"
    ]
}

GET /email/messages_webhooks/kinds

Запрос доступных событий

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

curl -X GET https://api.mailopost.ru/v1/email/messages_webhooks/events \
     -H 'Content-Type: application/json'              \
     -H 'Authorization: Bearer $API_TOKEN'

Пример ответа в случае успеха

{
    "events": [
        "delivered",
        "hard_bounced",
        "skipped",
        "opened",
        "clicked",
        "unsubscribed",
        "complained",
        "soft_bounced"
    ]
}

GET /email/messages_webhooks/events

SMTP

Подключение

Адрес: smtp.msndr.net

Для работы можно использовать следующие порты:

• 25 или 587 — для соединения без шифрования или с использованием STARTTLS

• 465 — в случае защищенного шифрованного соединения SSL/TLS

Аутентификация

Имя пользователя: 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>, объединенные запятой (см. пример выше). Вы можете использовать ID сообщений, чтобы запрашивать их статус через API или настроить отправку webhooks

К отправляемому сообщению можно добавлять собственные заголовки. Используйте заголовки формата X-My-Header: my value. Так, в указанном выше примере в результирующем сообщении будет присутствовать заголовок Client-Id: 123.

ИИ-ассистенты (MCP)

Кроме API, к аккаунту можно подключить ИИ-ассистента через MCP (Model Context Protocol): Claude, ChatGPT, Claude Code, Codex, OpenCode, Cursor, VS Code и другие клиенты, которые поддерживают удалённые MCP-серверы. Ассистент сам вызывает нужные инструменты: разбирает рассылки и отчёты, проверяет доставляемость и домены, готовит черновики, шаблоны, сегменты и группы, а с отдельными правами — отправляет рассылки после вашего подтверждения в чате.

По умолчанию доступ только на чтение. Запись и отправку вы разрешаете отдельно при подключении.

Адрес сервера

https://api.mailopost.ru/mcp

Транспорт — Streamable HTTP. Авторизация — OAuth 2.1 (вход в браузере, клиент регистрируется сам) или MCP-токен в заголовке:

Authorization: Bearer emcp_…

MCP-токен — это не ключ API: ключ API в MCP не принимается, а MCP-токен не работает в API.

Адрес сервера, подключения и MCP-токены собраны в личном кабинете: Настройки аккаунта => ИИ-ассистенты. Там же готовые команды для каждого клиента. Если раздела нет в кабинете или адрес сервера отвечает «не найдено», подключение ИИ-ассистентов для вашего аккаунта ещё не включено — напишите в поддержку.

Подключение через вход в браузере

Подходит для Claude и ChatGPT в браузере и для агентов на вашем компьютере. Пароль и ключ API ассистенту не передаются: вы входите на странице сервиса, выбираете аккаунт и права и нажимаете «Разрешить».

Claude (веб, десктоп): «Настройки» => «Коннекторы» => «Добавить свой коннектор», укажите адрес сервера и нажмите «Подключить».

ChatGPT: профиль => «Настройки» => «Плагины» => «Посмотреть каталог» => «Добавить» => «Создать пользовательский сервер MCP». Укажите название, адрес сервера и аутентификацию OAuth, нажмите «Создать в виде плагина», затем «Перейти к …».

Claude Code

claude mcp add --transport http mail https://api.mailopost.ru/mcp
claude mcp login mail

Codex

codex mcp add mail --url https://api.mailopost.ru/mcp
codex mcp login mail

OpenCode

opencode mcp add mail --url https://api.mailopost.ru/mcp
opencode mcp auth mail

Cursor: ~/.cursor/mcp.json, затем Settings => Tools & MCP => Connect

{
  "mcpServers": {
    "mail": {
      "url": "https://api.mailopost.ru/mcp"
    }
  }
}

VS Code: .vscode/mcp.json или настройки пользователя, затем Start

{
  "servers": {
    "mail": {
      "type": "http",
      "url": "https://api.mailopost.ru/mcp"
    }
  }
}

Браузер и агент должны работать на одном компьютере: после входа браузер возвращается на локальный адрес агента (http://localhost:<порт>/callback). Для агента на сервере используйте MCP-токен.

Подключение по MCP-токену

Для серверов, CI, n8n и скриптов, которые не могут войти через браузер. Токен создаётся в разделе Настройки аккаунта => ИИ-ассистенты => MCP-токены.

• срок действия — 7, 30, 90 дней или год;
• до 10 действующих токенов на пользователя;
• права выбираются при создании;
• токен показывается один раз;
• по токену недоступны отправка рассылок и одиночных писем, запуск триггеров, отписка и удаление получателей и webhook-уведомления — для них подключайтесь через вход в браузере.

Claude Code

claude mcp add --transport http mail https://api.mailopost.ru/mcp \
  --header "Authorization: Bearer emcp_…"

Codex

export MAIL_MCP_TOKEN=emcp_…
codex mcp add mail --url https://api.mailopost.ru/mcp \
  --bearer-token-env-var MAIL_MCP_TOKEN

Cursor: токен в переменной окружения MAILMCPTOKEN

{
  "mcpServers": {
    "mail": {
      "url": "https://api.mailopost.ru/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MAIL_MCP_TOKEN}"
      }
    }
  }
}

Держите MCP-токен в секрете: не кладите его в файлы проекта и не коммитьте в репозиторий.

Права

Ассистент видит только то, что разрешено при подключении. Права участника команды дополнительно ограничены его ролью.

Право	Что открывает	По умолчанию
account:read	организация, тариф, баланс, лимиты	всегда
campaigns:read	рассылки, отчёты, сравнение, шаблоны, триггеры	всегда
recipients:read	группы, параметры, сегменты; адреса получателей скрыты (iv***@mail.ru)	всегда
deliverability:read	домены отправки, DNS-записи, доставляемость	всегда
recipients:pii	адреса и значения параметров получателей целиком	по выбору
content:write	создание и изменение черновиков рассылок и шаблонов, сегменты, группы и их параметры, загрузка картинок в галерею, тестовое письмо себе	по выбору
recipients:write	загрузка до 1 000 получателей за раз в существующую группу	по выбору
send	отправка рассылок и одиночных писем, запуск триггеров — после подтверждения в чате; отмена рассылки и пауза триггера	по выбору, только через вход в браузере
destructive	отписка и удаление получателей, переименование и удаление параметров групп — после подтверждения в чате	по выбору, только через вход в браузере

Инструменты

Чтение: getaccount, getprofile, listcampaigns, getcampaign, getcampaignreport, comparecampaigns, getaccountsummary, listtemplates, gettemplate, gettemplatescreenshot, getcampaignscreenshot, listgroups, listrecipientparameters, listsegments, getsegment, previewsegment, findrecipient, listworkflows, getworkflow, listsenderdomains, getdeliverabilityreport, estimatecampaign, validateemailcontent, renderpreview, listgalleryimages.

Запись (content:write, recipients:write): createcampaigndraft, updatecampaigndraft, sendtestemail, createtemplate, updatetemplate, createsegment, creategroup, addgroupparameters, upsertrecipients, getimportstatus, uploadimage, creategalleryfolder, requestimageupload.

Отправка и управление (send, destructive): schedulecampaign, cancelcampaign, setworkflowstatus, listtransactionaltemplates, sendtransactionalemail, removerecipients, managegroupparameters, listwebhooks, manage_webhooks.

Список и схемы инструментов клиент получает сам (tools/list); описания инструментов написаны для модели.

Картинки для писем

Картинки письма ассистент кладёт в галерею аккаунта и вставляет в письмо их адрес — как это делается в кабинете. При отправке рассылки картинки из галереи копируются в сервис, а картинки с чужих сайтов — нет: проверка письма предупреждает о них (image_external).

• upload_image — по публичной ссылке http(s): сервис скачивает картинку сам, адреса внутренних сетей не открываются; маленький файл (до 1 МБ) можно передать в base64;
• request_image_upload — одноразовая ссылка на страницу, где человек загружает файлы с компьютера: 15 минут, до 10 файлов, перестаёт работать, если подключение отключено (вложения чата до MCP-сервера не доходят);
• list_gallery_images — папки и картинки галереи с полными адресами, create_gallery_folder — новая папка.

Принимаются JPEG, PNG и GIF до 10 МБ и до 2048 пикселей в ширину, как в галерее кабинета. Удалять и переименовывать картинки ассистент не умеет.

Подтверждение действий

Действия с последствиями — отправка, запуск триггера, отписка и удаление, webhook-уведомления — выполняются в два шага:

1. Первый вызов ничего не делает и возвращает сводку: что будет сделано, с цифрами (тема, отправитель, получатели, стоимость, предупреждения).
2. Ассистент показывает сводку и ждёт вашего «да».
3. Второй вызов с одноразовым кодом из сводки выполняет действие. Код действует 10 минут и только для этой сводки.

Рассылка, отправленная через ассистента, всегда проходит модерацию. Отмена рассылки и пауза триггера выполняются сразу, без сводки.

Изменения шаблонов и черновиков передают версию письма из get_template: если письмо изменили в кабинете после чтения, сервер откажет, и ассистент перечитает его.

Лимиты

Действие	Предел
Записей в одном ответе	200
Рассылки через ассистента	10 в сутки на аккаунт
Одиночные письма через ассистента	100 в сутки на аккаунт, поверх лимита API
Отписка и удаление	1 000 адресов за вызов, 10 000 в сутки
Тестовые письма	10 в час на подключение
Снимки писем	20 в минуту на подключение для каждого из двух инструментов
Загрузка картинок в галерею	30 в час на подключение, 200 в сутки на аккаунт

Сутки считаются по UTC.

Отключение

Подключения через вход и MCP-токены отключаются в разделе Настройки аккаунта => ИИ-ассистенты; доступ закрывается сразу. Подключения отзываются и автоматически — при смене пароля, блокировке аккаунта и удалении участника из команды. Удаление коннектора в самом ассистенте доступ на стороне сервиса не отзывает.

Примеры PHP запросов

Получение списка групп получателей

  <?php
  $base_url = 'https://api.mailopost.ru/v1/email/';
  $token = 'TOKEN';
  $headers = array(
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
  );
  $ch = curl_init($base_url . 'lists');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  $response = curl_exec($ch);
  curl_close($ch);
  echo $response . "\n";

Получение параметров для группы получателей

  <?php
  $base_url = 'https://api.mailopost.ru/v1/email/';
  $token = 'TOKEN';
  $headers = array(
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
  );
  $list_id = 'LIST ID';
  $ch = curl_init($base_url . 'lists/' . $list_id . '/parameters');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  $response = curl_exec($ch);
  curl_close($ch);
  echo $response . "\n";

Добавление получателя в группу

  <?php
  $base_url = 'https://api.mailopost.ru/v1/email/';
  $token = 'TOKEN';
  $headers = array(
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
  );
  $list_id = 'LIST ID';
  $parameter_id = 'PARAMETER ID';
  $data = array(
    'email'  => 'foo@bar.com',
    'values' => [
      array(
        'value' => 'Foo',
        'parameter_id' => $parameter_id
      )
    ]
  );
  $ch = curl_init($base_url . 'lists/' . $list_id . '/recipients');
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data, JSON_UNESCAPED_UNICODE));
  $response = curl_exec($ch);
  curl_close($ch);
  echo $response . "\n";

Импорт получателей в группу

  <?php
  $base_url = 'https://api.mailopost.ru/v1/email/';
  $token = 'TOKEN';
  $headers = array(
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
  );
  $list_id = 'LIST ID';
  $parameter_id = 'PARAMETER_ID';
  $data = array(
    'recipients' => [
      array(
        'email'  => 'foo@bar.com',
        'values' => [
          array(
            'value' => 'Foo',
            'parameter_id' => $parameter_id
          )
        ]
      ),
      array(
        'email'  => 'bar@foo.com',
        'values' => [
          array(
            'value' => 'Bar',
            'parameter_id' => $parameter_id
          )
        ]
      )
    ]
  );
  $ch = curl_init($base_url . 'lists/' . $list_id . '/recipients/imports');
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data, JSON_UNESCAPED_UNICODE));
  $response = curl_exec($ch);
  curl_close($ch);
  echo $response . "\n";

Отправка одиночного сообщения

  <?php
  $base_url = 'https://api.mailopost.ru/v1/email/';
  $token = 'TOKEN';
  $headers = array(
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
  );
  $from_email = 'SENDER';
  $to = 'RECIPIENT';
  $subject = 'Test';
  $text = 'Hello from API';
  $data = array(
    'from_email' => $from_email,
    'to' => $to,
    'subject' => $subject,
    'text' => $text
  );
  $ch = curl_init($base_url . 'messages');
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data, JSON_UNESCAPED_UNICODE));
  $response = curl_exec($ch);
  curl_close($ch);
  echo $response . "\n";

Отправка одиночного сообщения с вложениями

  <?php
  $base_url = 'https://api.mailopost.ru/v1/email/';
  $token = 'TOKEN';
  $headers = array(
    'Authorization: Bearer ' . $token,
  );
  $from_email = 'SENDER';
  $to = 'RECIPIENT';
  $subject = 'Test';
  $text = 'Hello from API';
  $data = array(
    'from_email' => $from_email,
    'to' => $to,
    'subject' => $subject,
    'text' => $text,
    'attachments[][0]' => curl_file_create('/path/to/file1'),
    'attachments[][1]' => curl_file_create('/path/to/file2')
  );
  $ch = curl_init($base_url . 'messages');
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
  $response = curl_exec($ch);
  curl_close($ch);
  echo $response . "\n";

Отправка сообщения по SMTP

<?php
error_reporting(E_ALL);
ini_set('display_errors', 1);
$smtp_config = [
  'host' => 'smtp.msndr.net',
  'port' => 587,
  'username' => 'CHANGE_ME',
  'password' => 'CHANGE_ME',
  'from' => 'CHANGE_ME',
  'to' => 'CHANGE_ME',
  'subject' => 'Test Subject',
  'message' => 'Test Message'
];
extract($smtp_config);
$s = fsockopen($host, $port);
if ($s) {
  fgets($s);
  fputs($s, "EHLO localhost\r\n"); while(fgets($s)){}
    $auth = base64_encode("\0" . $username . "\0" . $password);
  fputs($s, "AUTH PLAIN $auth\r\n");
  if (strpos(fgets($s), '235') !== false) {
    fputs($s, "MAIL FROM: <$from>\r\n"); fgets($s);
    fputs($s, "RCPT TO: <$to>\r\n"); fgets($s);
    fputs($s, "DATA\r\n"); fgets($s);
    fputs($s, "Subject: $subject\r\n\r\n$message\r\n.\r\n");
    echo "Result: " . fgets($s);
  } else {
    echo "Authentication failed";
  }
  fputs($s, "QUIT\r\n");
  fclose($s);
} else {
  echo "Connection failed";
}