Email-рассылки

Адресные книги

Путем использования API вы можете создавать адресные книги, редактировать их, удалять и проводить другие доступные операции со списками рассылки.

Создание книги

Для создания адресной книги отправляется POST запрос по ссылке

https://mailer-api.i.bizml.ru/addressbooks

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

bookName имя книги

В случае успеха сервер вернет ответ с ID значением созданной книги

Редактирование книги

Для редактирования адресной книги отправляется PUT запрос по ссылке

https://mailer-api.i.bizml.ru/addressbooks/{id}

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

id идентификатор адресной книги
name новое имя книги

В случае успеха сервер возвращает ответ со значением result = true

Получить список адресных книг

Для получения списка всех созданных адресных книг с подробной информацией по каждой из них отправляется GET запрос по ссылке

https://mailer-api.i.bizml.ru/addressbooks

Параметры запроса (необязательные):

limit количество записей
offset смещение выдачи (начиная с какой записи показывать)

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

https://mailer-api.i.bizml.ru/addressbooks?limit=10&offset=5

Параметры ответа:

id идентификатор книги
name имя книги
all_email_qty общее количество адресов
active_email_qty количество активных адресов
inactive_email_qty количество неактивных адресов
creationdate дата создания
status код статуса
status_explain объяснение статуса

Пример ответа для получения списка адресных книг:

[
{
    "id": "1",
    "name": "My first book",
    "all_email_qty": "1",
    "active_email_qty": "0",
    "inactive_email_qty": "1",
    "creationdate": "2015-04-20 08:52:40",
    "status": "0",
    "status_explain": "Active"
  },
  {
    "id": "2",
    "name": "My second book",
    "all_email_qty": "6",
    "active_email_qty": "0",
    "inactive_email_qty": "6",
    "creationdate": "2015-04-20 09:02:39",
    "status": "0",
    "status_explain": "Active"
  }
]

Информация по книге

Для получения детальной информации по одной конкретной адресной книге отправляется GET запрос по ссылке

https://mailer-api.i.bizml.ru/addressbooks/{id}

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

id идентификатор книги
name имя книги
all_email_qty общее количество адресов
active_email_qty количество активных адресов
inactive_email_qty количество неактивных адресов
creationdate дата создания
status код статуса
status_explain объяснение статуса

Пример ответа для информации по книге:

[

{

"id": "1",

"name": "My first book",

"all_email_qty": "1",

"active_email_qty": "0",

"inactive_email_qty": "1",

"creationdate": "2015-04-20 08:52:40",

"status": "0",

"status_explain": "Active"

},

]

Получить список переменных для адресной книги

Для получения детальной информации по пользовательским переменным конкретной адресной книги и их типах отправляется GET запрос по ссылке

https://mailer-api.i.bizml.ru/addressbooks/{id}/variables

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

id

идентификатор книги

Можно добавить произвольные пользовательские переменные, просто указав их список в запросе. Если такой переменной нет — она будет создана.

Получить список email адресов из книги

Для получения списка email адресов из конкретной адресной книги нужно сделать GET запрос по ссылке

https://mailer-api.i.bizml.ru/addressbooks/{id}/emails

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

id идентификатор книги
limit (необязательный) количество записей
offset (необязательный) смещение выдачи (начиная с какой записи показывать)

Пример URL запроса при передаче необязательных параметров:

https://mailer-api.i.bizml.ru/addressbooks/{id}/emails?limit=10&offset=5

Параметры ответа:

email адрес
status код статуса
status_explain объяснение статуса
variables массив с переменными для данного адреса

Пример ответа:

[

{

"email": "test@test.com",

"status": "0",

"status_explain": "New",

"variables": [

{

"name": "имя переменной",

"type": "string",

"value": "значение переменной"

},

{

"name": "имя переменной",

"type": "string",

"value": "значение переменной"

}

]

},

{

"email": "test2@test.com",

"status": "0",

"status_explain": "New",

"variables": [

{

"name": "имя переменной",

"type": "string",

"value": "значение переменной"

},

{

"name": "имя переменной",

"type": "string",

"value": "значение переменной"

}

]

}

]


Добавление email адресов в книгу

Нужно сделать POST запрос в виде ссылки

https://mailer-api.i.bizml.ru/addressbooks/{id}/emails

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

id идентификатор книги
emails сериализованный массив с email адресами

Пример структуры массива email адресов

[

{

"email": "test@test.com",

"variables": {

"имя переменной": "значение",

"имя переменной": "значение"

}

},

{

"email": "test2@test.com",

"variables": {

"имя переменной": "значение",

"имя переменной": "значение"

}

}

]

В случае успеха вернет JSON строку с result = true

Для добавления номера телефона используйте системную переменную "Phone".

Добавление подписчиков с письмом подтверждением (double-opt-in)

Чтобы применить double-opt-in активацию подписчика, необходимо в запрос добавить новый параметр: confirmation=force (необязательный параметр).

При этом появится обязательный параметр: sender_email — значением которого укажите email-адрес отправителя.

Адрес должен быть подтвержденным в личном кабинете в настройках сервиса в меню: «Рассылки» →  «Настройки сервиса»  «Новый адрес отправителя».

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

id идентификатор книги
email сериализованный массив с email адресами
confirmation (необязательный)  force
sender_email (обязательный) ваш адрес отправителя

Удаление адресов из адресной книги

Нужно сделать DELETE запрос по ссылке

https://mailer-api.i.bizml.ru/addressbooks/{list_id}/emails

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

id идентификатор книги
emails сериализованный массив с email адресами

Пример структуры массива email-адресов

[

"test@test.com",

"test2@test.com",

"test3@test.com",

"test4@test.com",

"test5@test.com"

]


В случае успеха вернет JSON строку с result = true

Получение информации по email адресу из адресной книги

Нужно сделать GET запрос по ссылке

https://mailer-api.i.bizml.ru/addressbooks/{id}/emails/{email}

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

id идентификатор книги
email еmail адрес, по которому нужно получить информацию

Параметры ответа:

email email адрес
abook_id идентификатор адресной книги
status код статуса
status_explain объяснение статуса
variables массив переменных для данного адреса

Пример ответа:

{

"email": "test@test.com",

"abook_id": "34",

"status": "1",

"status_explain": "Active",

"variables": [

{

"name": "имя переменной",

"type": "string",

"value": "значение"

},

{

"name": "имя переменной",

"type": "string",

"value": "значение"

},

{

"name": "имя переменной",

"type": "string",

"value": "значение"

}

]

}

Удаление адресной книги

Нужно сделать DELETE запрос по ссылке

https://mailer-api.i.bizml.ru/addressbooks/{id}

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

id идентификатор книги

В случае успеха вернет JSON строку с result = true

Расчет стоимости кампании, проведенной по адресной книге

Нужно сделать GET запрос по ссылке

https://mailer-api.i.bizml.ru/addressbooks/{id}/cost

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

id идентификатор книги

Параметры ответа:

cur валюта, которая использовалась для расчета
sent_emails_qty общее количество адресов для отправки
overdraftAllEmailsPrice цена за превышение лимита по email адресам
addressesDeltaFromBalance количество email, за которые будет взята плата с баланса
addressesDeltaFromTariff количество адресов, которые будут сняты по тарифу
max_emails_per_task ограничение тарифа по адресам
result хватает денег или нет (true — хватает, false — нет)

Пример ответа:

{

"cur": "RUR",

"sent_emails_qty": 16,

"overdraftAllEmailsPrice": 0,

"addressesDeltaFromBalance": 0,

"addressesDeltaFromTariff": 16,

"max_emails_per_task": "500",

"result": true

}

Кампании

Создание кампании

Нужно сделать POST запрос по ссылке

https://mailer-api.i.bizml.ru/campaigns

Действует ограничение — 4 рассылки в час.

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

sender_name имя отправителя
sender_email адрес отправителя
subject тема письма
body тело письма, кодированное в base64
list_id идентификатор адресной книги
send_date запланированная дата отправки (необязательный параметр). Должна быть в таком формате: Y-m-d H:i:s (например: 2016-02-02 23:34:23) и не может быть меньше текущей даты.
name имя кампании (необязательный параметр)
attachments вложенные файлы, сериализованный массив, в котором ключ — имя файла, а значение - содержимое файла (необязательный параметр)
type возможное значение — "draft" (рассылка будет создана как черновик)

Пример ответа:

{

"id": "27",

"status": "0",

"count": "0",

"tariff_email_qty": "1",

"paid_email_qty": "0",

"overdraft_price": "0",

"ovedraft_currency": "RUR"

}

Получить информацию по кампании

Нужно сделать GET запрос по ссылке

https://mailer-api.i.bizml.ru/campaigns/{id}

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

id идентификатор кампании

Пример ответа:

{

"id": "27",

"name": "Тестовая рассылка",

"message": {

"sender_name": "John Doe",

"sender_email": "JohnDoe@test.com",

"subject": "Моя первая рассылка",

"body": "<p>\ \ Привет мир!<\/p>",

"list_id": "28",

"attachments": "file.zip, file2.zip"

},

"status": "3",

"all_email_qty": 25,

"tariff_email_qty": "25",

"paid_email_qty": "0",

"overdraft_price": 0,

"overdraft_currency": "RUR",

"statistics": [

{

"code": 0,

"count": 1,

"explain": "In queue"

},

{

"code": 1,

"count": 24,

"explain": "Sent"

},

{

"code": 2,

"count": 22,

"explain": "Delivered"

},

{

"code": 3,

"count": 7,

"explain": "Opened"

},

{

"code": 4,

"count": 1,

"explain": "Link redirected"

},

{

"code": 17,

"count": 1,

"explain": "Temporary blocked"

}

]

}

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

Нужно сделать GET запрос по ссылке

https://mailer-api.i.bizml.ru/campaigns/{id}/email/{email}

Пример: https://mailer-api.i.bizml.ru/campaigns/3767327/email/john@gmail.com

Пример ответа:

{

"sent_date": "2017-06-19 15:14:46",

"global_status": 0,

"global_status_explain": "In queue",

"detail_status": 0,

"detail_status_explain": "In queue"

}

Получить список кампаний

Нужно сделать GET запрос по ссылке

https://mailer-api.i.bizml.ru/campaigns

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

limit количество записей (необязательный параметр)
offset смещение выдачи (начиная с какой записи показывать)

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

https://mailer-api.i.bizml.ru/campaigns?limit=10&offset=5

Пример ответа:

[

{

"id": "27",

"name": "Тестовая рассылка",

"message": {

"sender_name": "John Doe",

"sender_email": "JohnDoe@test.com",

"subject": "Моя первая рассылка",

"body": "<p>\ \ Привет мир!<\/p>",

"list_id": "28",

"attachments": "file.zip, file2.zip"

},

"status": "3",

"all_email_qty": 9712,

"tariff_email_qty": "9712",

"paid_email_qty": "0",

"overdraft_price": 0,

"overdraft_currency": "RUR"

}

]

Статистика по странам

Нужно сделать GET запрос по ссылке

https://mailer-api.i.bizml.ru/campaigns/{id}/countries

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

id идентификатор кампании

Параметры ответа:

RU код страны
34567 количество открытий

Пример ответа:

{

"UA": 23,

"RU": 34567

}

Статистика по рефералам

Нужно сделать GET запрос по ссылке

https://mailer-api.i.bizml.ru/campaigns/{id}/referrals

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

id идентификатор кампании

Параметры ответа:

link ссылка из письма
count количество переходов

Пример ответа:

[

{

"link": "http://first_link.com"

"count": 123454

},

{

"link": "http://second_link.com"

"count": 5463

}

]

Отменить отправку кампании

Нужно сделать DELETE запрос по ссылке

https://mailer-api.i.bizml.ru/campaigns/{id}

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

id идентификатор кампании

В случае успеха вернет JSON строку с result = true

Шаблоны

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

Нужно сделать POST запрос по ссылке

https://mailer-api.i.bizml.ru/template

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

name название шаблона (не обязательный параметр, в случае отсутствия будет проставлено имя вида Template YYYY.mm.dd H:i:s)
body верстка закодированная в base64

Пример ответа:

{

"result": true

}


Получить данные по шаблону

Нужно сделать GET запрос по ссылке

https://mailer-api.i.bizml.ru/template/{template_id}

ID можно получить при просмотре шаблонов по API

Пример полностью сформированной ссылки https://mailer-api.i.bizml.ru/template/ea2803ff79230a73a6c01d5b1e56022a

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

Нужно сделать GET запрос по ссылке:

https://mailer-api.i.bizml.ru/templates

Получить список всех системных шаблонов в аккаунте

Нужно сделать GET запрос по ссылке:

https://mailer-api.i.bizml.ru/templates/ru?owner=sendbox

Пример ответа:

[ {

"id": "2c39ff4e0c66f420e09265b85319e54e",

"lang": "en",

"name": "11111",

"created": "2015-04-23 09:38:23",

"tag": "",

"owner": "sendbox"

}, {

"id": "367370a076eca39454d907a8fe62ed82",

"lang": "en",

"name": "Arhitect",

"created": "0000-00-00 00:00:00",

"tag": "architect",

"owner": "sendbox"

}

]


Получить список всех пользовательских шаблонов в аккаунте

Нужно сделать GET запрос по ссылке:

https://mailer-api.i.bizml.ru/templates/?owner=me

Получить список всех пользовательских шаблонов в аккаунте на конкретном языке (на русском, например)

Нужно сделать GET запрос по ссылке:

https://mailer-api.i.bizml.ru/templates/ru/?owner=me

Отправители

Получить список всех отправителей

Нужно сделать GET запрос по ссылке

https://mailer-api.i.bizml.ru/senders

Пример ответа:

[

{

"name": "Иван Иванов"

"email": "JohnDoe@test.com",

"status": "Active"

},

{

"name": "Иван Иванов"

"email": "JaneDoe@test.com",

"status": "Active"

}

]

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

Нужно сделать POST запрос по ссылке

https://mailer-api.i.bizml.ru/senders

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

email адрес отправителя
name имя отправителя

В случае успеха сервер вернет JSON строку с result = true

Удаление отправителя

Нужно сделать DELETE запрос по ссылке

https://mailer-api.i.bizml.ru/senders

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

email адрес отправителя

В случае успеха сервер вернет JSON строку с result = true

Активация отправителя

Нужно сделать POST запрос по ссылке

https://mailer-api.i.bizml.ru/senders/{email}/code

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

code активационный код

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

{

"result": true,

"email": JohnDoe@test.com

}

Получить код активации отправителя на почту

Нужно сделать GET запрос по ссылке

https://mailer-api.i.bizml.ru/senders/{email}/code

Пример ответа:

{

"result": true,

"email": JohnDoe@test.com

}

В случае успеха на почту будет выслано письмо с кодом активации.

Email адрес

Получить общую информацию по адресу

Нужно сделать GET запрос по ссылке

https://mailer-api.i.bizml.ru/emails/{email}

Пример ответа:

{

"book_id": "39359",

"email": "test@test.com",

"status": "3",

"variables": [

{

"name": "имя переменной",

"type": "string",

"value": "значение переменной"

},

{

"name": "имя переменной",

"type": "string",

"value": "значение переменной"

},

{

"name": "имя переменной",

"type": "string",

"value": "значение переменной"

}

]

},

{

"book_id": "39362",

"email": "test@test.com",

"status": "3",

"variables": [

{

"name": "имя переменной",

"type": "string",

"value": "значение переменной"

}

]

}

]

Удалить адрес из всех книг

Нужно сделать DELETE запрос по ссылке

https://mailer-api.i.bizml.ru/emails/{email}

В случае успеха вернет JSON строку с result = true

Получить статистику для адреса по кампаниям

Нужно сделать GET запрос по ссылке

https://mailer-api.i.bizml.ru/emails/{email}/campaigns

Пример ответа:

{

"statistic": {

"sent": 0,

"open": 0,

"link": 0

},

"blacklist": false

}

Изменить значение переменной для существующего контакта

Для того чтобы изменить переменную для емейла необходимо отправить post-запрос на:

 https://mailer-api.i.bizml.ru/addressbooks/:addressBookId/emails/variable

Для корректной работы метода необходимо добавлять заголовок content-type: application/json.

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

{

"email": "myemail@example.com",

"variables": [

{

"name" : "name",

"value" : "John"

},

{

"name" : "number",

"value": 1

},

{

"name": "date",

"value" : "2019-02-01"

},

{

"name": "asdasd",

"value" : "asdasd"

}

]

}

https://mailer-api.i.bizml.ru/addressbooks/{list_id}/emails

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

email имейл получaтеля, для которого будет заменена переменная с именем name на значение John
addressBookId ID адресной книги, в которой находится нужный имеил и переменная с именем name

В переменную типа строка возможно установить как числовое значение, так и значение типа число или дата(YYYY-MM-DD); в переменную типа номер возможно установить только число. В переменную типа дата возможно установить только дату, которая передана в формате YYYY-MM-DD. Другие форматы не поддерживаются: к примеру, валидный формат даты : 2017-01-01, а не валидный: 2017-1-1.

Черный список (Blacklist)

Просмотреть черный список

Нужно сделать GET запрос по ссылке

https://mailer-api.i.bizml.ru/blacklist

Пример ответа:

[

"JohnDoe@test.com",

"JaneDoe@test.com",

]

Добавить адрес в черный список

Нужно сделать POST запрос по ссылке

https://mailer-api.i.bizml.ru/blacklist

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

emails строка с email адресами, разделенными запятыми, кодированная в base64
comment комментарий, строка (необязательный параметр)

Пример строки с email адресами, разделенными запятыми:

user1@mailserver.com,user2@mailserver.com,user3@mailserver.com

В случае успеха вернет JSON строку с result = true

Удалить адрес из черного списка

Нужно сделать DELETE запрос по ссылке

https://mailer-api.i.bizml.ru/blacklist

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

emails строка с email адресами, разделенными запятыми, кодированная в base64

Пример строки с email-адресами, разделенными запятыми:

 

user1@mailserver.com,user2@mailserver.com,user3@mailserver.com

В случае успеха вернет JSON строку с result = true

Баланс

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

Нужно сделать GET запрос по ссылке

https://mailer-api.i.bizml.ru/balance

Необязательный параметры запроса — значение валюты.

При использовании необязательного параметра (значения валюты) ссылка будет иметь следующий вид:

https://mailer-api.i.bizml.ru/balance/USD

Пример ответа:

{

"currency": "USD",

"balance_currency": 0.02

}

WebHooks

Webhook — механизм получения уведомлений об определённых событиях.

Для включения webhook зайдите в раздел «Настройки аккаунта» → «API» и нажмите на кнопку «Создать webhook».

Далее укажите URL, на который будут отправляться уведомления, и какие именно события нужно передавать.

Список событий, по которым срабатывает webhook в email сервисе, относительно отправки письма:

  • Отмечено как спам
  • Открытие рассылки
  • Переход по ссылке
  • Новый подписчик
  • Удаление из книги
  • Пользователь отписался
  • Изменение статуса рассылки

При срабатывании webhook, мы отсылаем на указанный клиентом url данные

  • тип данных: JSON
  • тип запроса: POST

Данные отсылаются каждую минуту или же при достижении лимита в 100 событий.

Если событий несколько, то они будут сгруппированы в один или несколько запросов:

[

{

"timestamp": 1496827422,

"event": "delete",

"book_id": "490686",

"email": "john.doe@annbakery.ru"

},

{

"timestamp": 1496827422,

"event": "delete",

"book_id": "490686",

"email": "doe.john@annbakery.ru"

},

{

"timestamp": "1496827625",

"variables": [],

"email": "john.doe@annbakery.ru",

"source": "address book",

"book_id": "490686",

"event": "new_emails"

}

]

Форматы запросов, в зависимости от события:

Помечено как спам:

[

{

"timestamp": 1496827422,

"event": "spam",

"task_id": 3668141,

"email": "john.doe@annbakery.ru"

}

]


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

[

{

"task_id": 3668141,

"timestamp": "1496827941",

"open_device": "Desktop",

"open_platform": "Windows",

"browser_ver": "11.0",

"browser_name": "Firefox",

"email": "john.doe@annbakery.ru",

"event": "open"

}

]

Переход по ссылке:

[

{

"task_id": 3668141,

"timestamp": "1496828000",

"open_device": "Desktop",

"open_platform": "Linux",

"browser_ver": "58.0.3029.110",

"browser_name": "Chrome",

"link_id": 71741389,

"email": "john.doe@annbakery.ru",

"event": "redirect"

}

]

Пользователь отписался:

[

{

"task_id": "3668141",

"timestamp": "1496827872",

"from_all": 1,

"email": "john.doe@annbakery.ru",

"reason": null,

"book_id": 490686,

"event": "unsubscribe",

"categories": ""

}

]

Новый подписчик:

[

{

"timestamp": "1496827625",

"variables": [],

"email": "john.doe@annbakery.ru",

"source": "address book",

"book_id": "490686",

"event": "new_emails"

},

{

"timestamp": "1496827625",

"variables": [],

"email": "doe.john@annbakery.ru",

"source": "subscription form",

"book_id": "490686",

"event": "new_emails"

}

]

Удаление из книги:

[

{

"timestamp": 1496827422,

"event": "delete",

"book_id": "490686",

"email": "john.doe@annbakery.ru"

}

]

Изменение статуса рассылки:

[

{

"status": "approve",

"status_explain": "Approved and will be sent",

"task_id": 3668138,

"timestamp": 1496827843,

"book_id": "490686",

"event": "task_status_update"

},

{

"status": "approve_part",

"status_explain": "Approved and will be sent by part",

"task_id": 3668139,

"timestamp": 1496827843,

"book_id": "490686",

"event": "task_status_update"

},

{

"status": "only_active",

"status_explain": "Will be sent only on active adresses",

"task_id": 3668140,

"timestamp": 1496827843,

"book_id": "490686",

"event": "task_status_update"

},

{

"status": "confirm_addresses",

"status_explain": "Rejected: you need to confirm your mailing list",

"task_id": 3668142,

"timestamp": 1496827843,

"book_id": "490686",

"event": "task_status_update"

},

{

"status": "need_edit",

"status_explain": "Rejected: You need to edit your mail body",

"task_id": 3668143,

"timestamp": 1496827843,

"book_id": "490686",

"event": "task_status_update"

},

{

"status": "rejected",

"status_explain": "Campaign was rejected",

"task_id": 3668144,

"timestamp": 1496827843,

"book_id": "490686",

"event": "task_status_update"

},

{

"status": "on_moderation",

"status_explain": "Your campaign on moderation",

"task_id": 3668145,

"timestamp": 1496827843,

"book_id": "490686",

"event": "task_status_update"

},

{

"status": "sending",

"status_explain": "Your campaign in sending queue",

"task_id": 3668146,

"timestamp": 1496827843,

"book_id": "490686",

"event": "task_status_update"

},

]

Пример скрипта, принимающего запрос, на языке PHP:

<?php

$json_string = file_get_contents('php://input');

$data_array = json_decode($json_string, true);

?>