Главная — Разработчикам

Разработчикам: API и SMTP

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

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

Базовый URL

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

https://email.mailer.by/api/v1

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

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

Authorization: Bearer $API_TOKEN

Ключ для доступа к API можно получить в личном кабинете.

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

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

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

Content-Type: application/json

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

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

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

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

curl -X GET https://email.mailer.by/api/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

При выполнении запроса с использованием списка данных ответ будет возвращен в виде структуры:

Пример ответа со списком данных (Collection)

  {
    "total_count":23,
    "total_pages":7,
    "page_number":2,
    "page_size":3,
    "collection":[
      {
        "id":1,
        "title":"My Recipients"
      },
      {
        "id":2,
        "title":"My Recipients #2"
      },
      {
        "id":3,
        "title":"My Recipients #3"
      }
    ]
  }

Ключ	Описание
total_count	Общее количество элементов "collection"
total_pages	Количество страниц
page_number	Номер текущей страницы
page_size	Количество записей на странице
collection	Массив возвращаемых данных

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

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

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

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

Коды ответов

Код	Описание
2xx	Запрос успешно выполнен
400	Неверные параметры
401	Аутентификация не пройдена
402	Недостаточно средств
404	Ресурс не найден
415	Неподдерживаемый тип данных
422	Ресурс не может быть обработан

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

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

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

curl -X POST https://email.mailer.by/api/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>",
  "status":"queued",
  "events": {
    "open": 1,
    "redirect": {
      "http://foo.com": 2,
      "http://bar.com": 3
    },
    "spam": 1,
    "unsubscribe": 1
  }
}

POST /email/messages

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

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

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

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

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

Ответ сервера содержит 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	Пользователь отписался

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

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

curl -X GET https://email.mailer.by/api/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://email.mailer.by/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://email.mailer.by/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://email.mailer.by/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://email.mailer.by/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://email.mailer.by/v1/email/templates/:template_id/messages \
     -H 'Content-Type: application/json'        \
     -H 'Authorization: Bearer $API_TOKEN'      \
     -d '...JSON...'

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

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

curl -X POST https://email.mailer.by/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	Тарифицируется "письмо". Если нет "писем", возвращается ошибка.

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

Группа получателей - элемент необходимый для отправки Email рассылки, этот элемент обязательно содержит список email адресов, по необходимости может быть дополнен произвольными пареметрами.

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

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

{
  "title":"My Recipients"
}

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

curl -X POST https://email.mailer.by/api/v1/email/lists \
     -H 'Content-Type: application/json'          \
     -H 'Authorization: Bearer $API_TOKEN'        \
     -d 'Request JSON'

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

{
  "id":1,
  "title":"My Recipients"
}

POST /email/lists

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

Параметр	Описание	Обязательный
title	Название группы получателей. Должно быть уникальным	Да

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

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

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

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

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

curl -X GET https://email.mailer.by/api/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://email.mailer.by/api/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	Название группы

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

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

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

{
  "title":"Age",
  "kind": "numeric"
}

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

curl -X POST https://email.mailer.by/api/v1/email/lists/1/parameters \
     -H 'Content-Type: application/json'                       \
     -H 'Authorization: Bearer $API_TOKEN'                     \
     -d '...JSON...'

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

{
  "id":11,
  "title":"Age",
  "kind":"numeric",
  "list_id":15
}

POST /email/lists/:id/parameters

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

Параметр	Описание	Обязательный
title		Да
kind	Возможные значения: `string` `numeric` `date` `boolean` `geo` Значение по умолчанию: `string`

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

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

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

Список параметров

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

curl -X GET https://email.mailer.by/api/v1/email/lists/1/parameters \
     -H 'Content-Type: application/json'                      \
     -H 'Authorization: Bearer $API_TOKEN'

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

{
  "total_count":2,
  "total_pages":1,
  "page_number":1,
  "page_size":25,
  "collection":[
    {
      "id":1,
      "title":"Name",
      "kind":"string",
      "list_id":1
    },
    {
      "id":2,
      "title":"Age",
      "kind":"numeric",
      "list_id":1
    }
  ]
}

GET /email/lists/:id/parameters

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

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

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

Получатели

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

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

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

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

curl -X POST https://email.mailer.by/api/v1/email/lists/1/recipients \
     -H 'Content-Type: application/json'                       \
     -H 'Authorization: Bearer $API_TOKEN'                     \
     -d '...JSON...'

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

{
  "id":1,
  "email":"alice@example.org",
  "list_id":1,
  "values":[
    {
      "value":"Alice",
      "kind":"string",
      "parameter_id":1
    },
    {
      "value":22.0,
      "kind":"numeric",
      "parameter_id":2
    }
  ]
}

POST /email/lists/:id/recipients

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

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

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

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

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

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

Атрибут	Описание
id	Идентификатор
email	Адрес
values	Массив значений

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

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

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

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

{
  "email":"alice@example.org",
  "values":[
    {
      "parameter_id":"1",
      "value":"Alice"
    },
    {
      "parameter_id":"2",
      "destroy":"true"
    }
  ]
}

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

curl -X PATCH https://email.mailer.by/api/v1/email/lists/1/recipients/1 \
     -H 'Content-Type: application/json'                     \
     -H 'Authorization: Bearer $API_TOKEN'                   \
     -d '...JSON...'

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

{
  "id":1,
  "email":"alice@example.org",
  "list_id":1,
  "values":[
    {
      "value":"Alice",
      "kind":"string",
      "parameter_id":1
    }
  ]
}

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

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

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

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

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

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

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

Атрибут	Описание
id	Идентификатор
email	Адрес
values	Массив значений

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

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

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

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

curl -X POST https://email.mailer.by/api/v1/email/recipients \
     -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,
      "email":"alice@example.org",
      "list_id":1,
      "values":[
        {
          "value":"Alice",
          "kind":"string",
          "parameter_id":9
        },
        {
          "value":22.0,
          "kind":"numeric",
          "parameter_id":10
        }
      ]
    },
    {
      "id":2,
      "email":"bob@example.org",
      "list_id":1,
      "values":[

      ]
    }
  ]
}

GET /email/lists/:id/recipients

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

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

Атрибут	Описание
id	Идентификатор
email	Адрес
values	Массив значений

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

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

Импорт большого количества получателей

POST /email/lists/:id/recipients/imports

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

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

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

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

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

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

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

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

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

{
  "recipients":[
    {
      "email":"alice@example.org",
      "values":[
        {
          "parameter_id":"1",
          "value":"Alice"
        },
        {
          "parameter_id":"2",
          "value":"22"
        }
      ]
    },
    {
      "email":"bob@example.org",
      "values":[
        {
          "parameter_id":"1",
          "value":"Bob"
        },
        {
          "parameter_id":"2",
          "value":"11"
        }
      ]
    }
  ]
}

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

curl -X POST https://email.mailer.by/api/v1/email/lists/1/recipients/imports \
     -H 'Content-Type: application/json'                       \
     -H 'Authorization: Bearer $API_TOKEN'                     \
     -d '...JSON...'

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

{
  "id":7,
  "status":"queued"
}

Организации

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

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

{
  "name":"My Organization",
  "address":"Lenina 40",
  "country":"Belarus",
  "city":"Minsk",
  "phone":"+375-29-123-4567",
  "zip":"220000"
}

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

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

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

{
  "id":1,
  "name":"My Organization",
  "address":"Lenina 40",
  "country":"Belarus",
  "city":"Minsk",
  "phone":"+375-29-123-4567",
  "zip":"220000",
  "current":true
}

POST /email/organizations

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

Параметр	Описание	Обязательный
name		Да
address		Да
country		Да
city		Да
phone		Да
zip		Да

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

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

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

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

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

curl -X GET https://email.mailer.by/api/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":"Belarus",
      "city":"Minsk",
      "phone":"+375-29-123-4567",
      "zip":"220000",
      "current":true
    }
  ]
}

GET /email/organizations

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

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

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

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

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

curl -X GET https://email.mailer.by/api/v1/email/organizations/1 \
     -H 'Content-Type: application/json'                   \
     -H 'Authorization: Bearer $API_TOKEN'

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

{
  "id":1,
  "name":"My Organization",
  "address":"Lenina 40",
  "country":"Belarus",
  "city":"Minsk",
  "phone":"+375-29-123-4567",
  "zip":"220000",
  "current":true
}

GET /email/organizations/:id

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

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

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

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

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

curl -X GET https://email.mailer.by/api/v1/email/organizations/current \
     -H 'Content-Type: application/json'                         \
     -H 'Authorization: Bearer $API_TOKEN'

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

{
  "id":1,
  "name":"My Organization",
  "address":"Lenina 40",
  "country":"Belarus",
  "city":"Minsk",
  "phone":"+375-29-123-4567",
  "zip":"220000",
  "current":true
}

GET /email/organizations/current

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

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

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

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

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

curl -X PATCH https://email.mailer.by/api/v1/email/organizations/1/current \
     -H 'Content-Type: application/json'                                 \
     -H 'Authorization: Bearer $API_TOKEN'

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

{
  "id":1,
  "name":"My Organization",
  "address":"Lenina 40",
  "country":"Belarus",
  "city":"Minsk",
  "phone":"+375-29-123-4567",
  "zip":"220000",
  "current":true
}

PATCH /email/organizations/:id/current

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

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

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

Рассылки

Создание рассылки

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

{
  "from_email":"hello@world.com",
  "subject":"Hello World",
  "text":"Hello World",
  "html":"<h1>Hello World</h1>",
  "lists":[
    {
      "id":"1"
    }
  ]
}

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

curl -X POST https://email.mailer.by/api/v1/email/campaigns \
     -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":"draft",
  "recipients_count":10,
  "purchase":{
    "enable":true,
    "subscribers":10,
    "credits":0,
    "deficit":0
  },
  "statistics":{
    "delivered":1,
    "bounced":0,
    "delivering":0,
    "uniq_open":0,
    "uniq_click":0,
    "unsubscription":0,
    "spam":0
  }
}

POST /email/campaigns

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

Параметр	Описание	Обязательный
from_email		Да
subject		Да
from_name
text		Должен присутствовать хотя бы один параметр: `text` или `html`
html		Должен присутствовать хотя бы один параметр: `text` или `html`
lists	Массив групп получателей	Да

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

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

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

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

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

Статусы

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

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

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

Статистика

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

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

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

curl -X PATCH https://email.mailer.by/api/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,
    "uniq_click":0,
    "unsubscription":0,
    "spam":0
  }
}

PATCH /email/campaigns/:id/deliver

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

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

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

Статусы

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

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

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

Статистика

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

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

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

curl -X GET https://email.mailer.by/api/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,
    "uniq_click":0,
    "unsubscription":0,
    "spam":0
  }
}

GET /email/campaigns/:id

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

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

Статусы

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

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

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

Статистика

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