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

Данный документ содержит сведения о программном интерфейсе сервиса 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) - постраничный способ выдачи данных, используемый в некоторых методах. Для управления страницами выдачи списка данных в заголовках запроса необходимо передавать параметры 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_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"
      }
    ]
  }

Обработка ответа

Обработка ответа может осуществляться при проверки кода состояния HTTP запроса. Так же в случае неуспешного выполнения запроса, ответ содержит массив данных c описанием ошибок в формате JSON.

Пример ответа с ошибками

{
  "errors":[
    {
      "code":400,
      "detail":"subject is empty"
    }
  ]
}

Коды ответов

Ограничения

Для предотвращения отправки нежелательных писем (спам), отправляемых по 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 со следующими атрибутами:

Одиночные сообщения

Отправка одиночного 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

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

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

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

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

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

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

Обратите внимание, что при отправке сообщений сервер может вернуть ответ со статусом 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 со следующими атрибутами:

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

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

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

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

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

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

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

Статусы

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

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

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 - идентификатор шаблона

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

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

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"
  }
}

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

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

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 со следующими атрибутами:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 содержит следующие атрибуты:

Удаление группы

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

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 - идентификатор группы для запроса информации

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

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

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

Параметры группы получателей

Создание параметра

Метод создает новый параметр в группе

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

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

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

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

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

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

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

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

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

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

Изменение параметра

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

Пример 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 - идентификатор параметра

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

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

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

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

Метод удаляет параметр из группы получателей

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

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

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

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

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

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

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

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

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

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

Данный метод позволяет получить информацию о получателе по 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Параметр run_triggers

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

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

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

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

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

Организации

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

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

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

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

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

Список организаций

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

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

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

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

Информация об организации

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

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 со следующими атрибутами:

Организация по умолчанию

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

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 со следующими атрибутами:

Задать организацию по умолчанию

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

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 со следующими атрибутами:

Изменение организации

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

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

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

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

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

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

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

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

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

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

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

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

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

Статистика

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

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

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

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

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

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

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

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

Статусы

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

Статистика

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

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

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

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

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

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

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

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

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

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 со следующими атрибутами:

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

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

Статистика

Webhooks

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

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

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

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

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

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

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

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

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

{
  "meta": {
      "id": 1,
      "name": "Рассылка постоянным клиентам",
      "type": "campaign"
    },
  "events": [
    {
      "name": "delivered",
      "email": "example@gmail.com",
      "timestamp": 1684400000
    },
    {
      "name": "opened",
      "email": "example@gmail.com",
      "timestamp": 1684401111
    },
    {
      "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"
    },
    {
      "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

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

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

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

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

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

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

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

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

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

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

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 со следующими атрибутами:

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

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

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

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

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

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

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

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 со следующими атрибутами:

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

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

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.

Готовые интеграции

У нас уже есть готовые интеграции с различными сервисами. Доступна интеграция с Tilda, LPgenerator и еще десятками популярных сервисов через онлайн-коннектор Albato.