1. Главная
  2. Интеграции
  3. API
  4. API Email Service
 

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

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

 

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

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

https://api.sendpulse.com/addressbooks

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

bookName имя книги

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

 

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

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

https://api.sendpulse.com/addressbooks/{id}

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

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

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

 

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

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

https://api.sendpulse.com/addressbooks

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

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

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

https://api.sendpulse.com/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"
  }
]

Возможные статусы адресной книги:

Код статуса Описание статуса
0 Активная адресная книга
1 Книга помечена как удаленная
3 Ожидается ответ от пользователя на уточняющий вопрос модератора
4 Адресная книга заблокирована сервисом на время загрузки в нее адресов
5 Адресная книга заблокирована демоном на время переноса из нее адресов в кампанию; после разблокирования выставляется статус «0»

 

 

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

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

https://api.sendpulse.com/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"
  }
]

Возможные статусы адресной книги:

Код статуса Описание статуса
0 Активная адресная книга
1 Книга помечена как удаленная
3 Ожидается ответ от пользователя на уточняющий вопрос модератора
4 Адресная книга заблокирована сервисом на время загрузки в нее адресов
5 Адресная книга заблокирована демоном на время переноса из нее адресов в кампанию; после разблокирования выставляется статус «0»
 

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

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

https://api.sendpulse.com/addressbooks/{id}/variables

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

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

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

[
    {
        "name": "емейл",
        "type": "string"
    },
    {
        "name": "имя",
        "type": "string"
    },
    {
        "name": "дата",
        "type": "data"
    },
    {
        "name": "код",
        "type": "number"
    }
]
 

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

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

https://api.sendpulse.com/addressbooks/{id}/emails

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

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

Метод возвращает до 100 записей, для смещения выдачи результатов используйте параметры запроса limit и offset.

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

https://api.sendpulse.com/addressbooks/{id}/emails?limit=10&offset=5

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

[ 
   { 
      "email":"test@test.com",
      "status": 0,
      "status_explain":"New",
      "variables":{ 
         "имя":"Евгения",
         "город":"Киев"
      }
   },
   { 
      "email":"test2@test.com",
      "status": 0,
      "status_explain":"New",
      "variables":{ 
         "имя":"Михаил",
         "город":"Москва"
      }
   }
]

Пример ответа, если значение переменных пусто:

[
    {
        "email": "test@test.com",
        "status": 0,
        "phone": "",
        "status_explain": "New",
        "variables": []
    }
]

Возможный статус имейла:

Код статуса Описание статуса
0 Новый — только что загруженный адрес, рассылка на него запрещена, пока адрес не будет активирован. Активация проводится администрацией сервиса.
1 Активный — рассылка на него разрешена. Если адрес не активирован, рассылка на него не уходит.
2 Запрошена активация — отправлено письмо владельцу адреса. Получателю рассылки отправлено письмо с просьбой подтвердить подписку на рассылку.
3 Запрошена активация — активация осуществляется через нашу панель администратора.
4 Отписался от рассылки — получатель рассылки отказывается от получения писем от данного пользователя.
5 Отклонен сервисом — отклонен через панель администратора сервиса.
6 Отписался от всех рассылок — адрес блокируется сервисом при поступлении жалоб от получателей рассылки либо пользователь нажал на ссылку «Отписаться от всего».
7 Письмо на активацию отправлено пользователю.
8 Адрес заблокирован клиентом самостоятельно.
9 На данный адрес невозможно сделать рассылку (статус выставляется при ошибки отправки на этот адрес).
10 Блокировка по списоку хостов.
11 Блокировка по имени пользователя.
12 Блокировка по части адреса.
13 Адрес удален клиентом.
14 Временно недоступен.
 

Получить общее количество адресов в книге

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

https://api.sendpulse.com/addressbooks/{id}/emails/total

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

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

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

{
    "total": 1
}
 

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

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

https://api.sendpulse.com/addressbooks/{id}//variables/{variableName}/{searchValue}

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

id идентификатор книги
variableName имя переменной в адресной книге, по которому необходимо искать
searchValue значение переменной, которую необходимо найти во всех контактах

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

[
    {
        "email": "a.kozlov@art-industria.ru",
        "status": 0,
        "status_explain": "New"
    },
    {
        "email": "e.darkling@gmail.com",
        "status": 1,
        "status_explain": "Active"
    }
]
 

Добавление email адреса в книгу (методом single-opt-in)

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

https://api.sendpulse.com/addressbooks/{id}/emails

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

id идентификатор книги
emails сериализованный массив контактов (пример ["example@gmail.com", "example@outlook.com"])

если же нужно передать не только емейл, но и переменные, то используется следующая структура передачи значений:
email емейл адрес подписчика
variables (необязательный параметр)

сериализованный массив переменных {"имя переменной":"значение переменной"}.

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

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

{
"emails":[
  {
    "email": "test@test.com",
    "variables": {
      "Имя": "Елизавета",
      "Phone": "380632727700"
    }
  },
  {
    "email": "test2@test.com",
    "variables": {
      "имя переменной": "значение"
    }
  }
]
}

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

 

Добавление email адреса в книгу (методом double-opt-in)

Для того, чтобы применить double-opt-in активацию подписчика (контакт попадет в книгу только после подтверждения отправления на почту), необходимо в запрос добавить новые параметры запроса: confirmation=force и sender_email — значением которого укажите email-адрес отправителя.

Адрес должен быть подтвержденным в личном кабинете в настройках сервиса в меню тут . (настройки сервиса ->адреса отправителя)

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

https://api.sendpulse.com/addressbooks/{id}/emails

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

id идентификатор книги
emails сериализованный массив контактов (пример ["example@gmail.com", "example@outlook.com"] )

если же нужно передать не только емейл, но и переменные, то используется следующая структура передачи значений:
email емейл адрес подписчика
variables (необязательный параметр)

сериализованный массив переменных {"имя переменной":"значение переменной"}
confirmation force
sender_email адрес отправителя, от которого отправится письмо подтверждение
template_id идентификатор письма подтверждения, создается в настройках сервиса (если параметр не указывается, отправится письмо которое выбрано в настройках "по умолчанию"). Пример a3e45169-7ae7-4a39-b457-72fd04401f26
message_lang язык письма подтверждения, может принимать значения "ru", "en", "ua", "tr", "es", "pt"
 

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

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

https://api.sendpulse.com/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

 

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

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

https://api.sendpulse.com/addressbooks/{id}

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

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

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

 

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

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

https://api.sendpulse.com/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://api.sendpulse.com/campaigns

Ограничение - 4 рассылки в час!

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

sender_name имя отправителя
sender_email адрес отправителя
subject тема письма
body тело письма, кодированное в base64
template_id идентификатор шаблона загруженного или созданного в сервисе. Получить ид шаблона можно при помощи метода, описанного тут (можно использовать параметры ответа real_id или id)
body_amp* тело АМП версии письма, кодированное в base64 (дополнительный необязательный параметр)
list_id идентификатор адресной книги
segment_id идентификатор сегмента созданного в аккаунте ([Адресные книги] -> выбрать книгу -> [Cегменты] -> [Мои сегменты] -> выбрать сегмент -> cкопировать значение id сегмента с URL в адресной строке)
send_test_only список адресов в json формате ["harward@test.com"]
если этот параметр есть, то рассылка будет отправлена лишь на те адреса которые указаны в данном параметре
можно указывать максимум 3 адреса
можно отправить максимум 20 таких сообщений за час 
в url необходимо отправлять PATCH запрос, не POST для отправки теста
(необязательный параметр)
send_date Запланированная дата отправки (необязательный параметр). Должна быть в таком формате: Y-m-d H:i:s (например: 2016-02-02 23:34:23) и не может быть меньше текущей даты.
name имя кампании (необязательный параметр)
attachments вложенные файлы, сериализованный массив, в котором ключ - имя файла, а значение - содержимое файла (необязательный параметр)
{"name":"содержимое_файла/путь_к_файлу"} (необязательный параметр)
type Возможное значение - draft (рассылка будет создана как черновик).

*Примечание: код тела AMP должен быть валидным и передавать можно только после подтверждения от google и mail.ru. Подать заявку на рассмотрение можно вот тут. 

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

{
  "id": 27,
  "status": 0,
  "count": 0,
  "tariff_email_qty": 1,
  "paid_email_qty": 0,
  "overdraft_price": 0,
  "ovedraft_currency": "RUR"
}
 

Редактирование запланированной кампании

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

https://api.sendpulse.com/campaigns/{id}

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

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

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

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

https://api.sendpulse.com/campaigns/{id}

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

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

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

{
    "id": 10113867,
    "name": "This is just a test",
    "message": {
        "sender_name": "Питер",
        "sender_email": "news@discoverytale.com",
        "subject": "This is just a test",
                "attachments": "file.zip, file2.zip",
        "list_id": 2128929
    },
    "status": 3,
    "all_email_qty": 1000,
    "tariff_email_qty": 1000,
    "paid_email_qty": 0,
    "overdraft_price": 0,
    "overdraft_currency": "RUR",
    "statistics": [
        {
            "code": 1,
            "count": 1000, //количество отправленных
            "explain": "Sent"
        },
        {
            "code": 2,
            "count": 999, //количество доставленных
            "explain": "Delivered"
        },
        {
            "code": 3,
            "count": 400, //количество открытых
            "explain": "Opened"
        },
        {
            "code": 4,
            "count": 300, //количество переходов по ссылке
            "explain": "Link redirected"
        }
{
            "code": 18,
            "count": 1, //количество ошибок
            "explain": "Disable by administrator"
        }
    ],
    "send_date": "2017-08-08 06:08:31",
    "permalink": "http://archive.sendpulse.com/60rwr/" //постоянная ссылка на рассылку (архив)
}

Возможный статус кампании:

Код статуса Описание статуса
0 Новое задание на рассылку
1 Ожидается отправка (на модерации)
2 Отправляется
3 Отправлено
4 Тестовая отправка (на имейл пользователя)
5 Рассылка заблокирована (администрацией)
6 Рассылка помечена для удаления
7 Обновление статусов (последует статус «3»)
8 Тестовая кампания отправлена
9 Идет отправка
10 Обрабатывается, готовится к отправке
11 Ожидается ответ от пользователя на уточняющий вопрос модератора
12 Нет активных адресов
13 Кампания в процессе создания — адреса из адресной книги переносятся в кампанию. После окончания переноса выставляется статус «2» для адресов меньше 20-ти или «1» в ином случае.
14 Кампания создана и отправлена в очередь для отправки. После отправки статус изменится на «3».
15 Кампания ожидает итога A/B тестирования
16 Отправка кампании отменена пользователем
22 Отправляется частично
23 Отправлена частично
25 Рассылка заблокирована администрацией после частичной отправки
26 Черновик
27 Необходимо редактирование
28 Запланирована отправка по непрочитанным
33 Автосерии. Для отправки рассылки не хватило средств на балансе
36 Черновик автосерии

Возможный статус адресов в компании:

0 Сообщение пока ещё не отправлено и находится в очереди на отправку
1 Сообщение отправлено, но статус доставки пока неизвестен. Статус временный и может измениться
2 Сообщение доставлено. Может измениться на 3, 4 или 5.
3 Сообщение доставлено и зарегистрировано его прочтение. Может измениться на 4 или 5
4 Сообщение доставлено, прочитано и выполнен переход по одной из ссылок. Может измениться на 5
5 Сообщение доставлено и прочитано, но пользователь отписался по ссылке в письме. Статус окончательный
6 Адрес не существует, доставка не удалась. Статус окончательный
7 Временно недоступен
8 Недоступен
9 Письмо отклонено сервером как спам
10 Почтовый ящик получателя переполнен
11 Адресат считает письмо спамом
12 Доставка не удалась по иным причинам. Статус окончательный
13 Не отправлено. Статус окончательный
14 Домен не существует. Статус окончательный
15 Отписался от рассылки. Статус окончательный
16 Отправка не удалась, email адрес невалидный
17 Отправка временно запрещена
18 Отключено администратором
 

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

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

https://api.sendpulse.com/campaigns

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

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

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

https://api.sendpulse.com/campaigns?limit=10&offset=5

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

[
  {
    "id": 27,
    "name": "Тестовая рассылка",
    "message": {
      "sender_name": "John Doe",
      "sender_email": "JohnDoe@test.com",
      "subject": "Моя первая рассылка",
      "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://api.sendpulse.com/addressbooks/{id}/campaigns

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

id идентификатор книги
limit количество записей (необязательный параметр)
offset смещение выдачи (начиная с какой записи показывать) 
[
    {
        "task_id": 9147533,
        "task_name": "тест",
        "task_status": 3
    },
    {
        "task_id": 9156025,
        "task_name": "Campaign_6741804_UM99",
        "task_status": 3
    }
]
 

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

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

https://api.sendpulse.com/campaigns/{id}/countries

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

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

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

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

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

{
  "UA": 23,
  "RU": 34567
}
 

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

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

https://api.sendpulse.com/campaigns/{id}/referrals

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

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

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

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

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

[
  {
    "link": "http://first_link.com"
    "count": 123454
  },
  {
    "link": "http://second_link.com"
    "count": 5463
  }
]
 

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

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

https://api.sendpulse.com/campaigns/{id}

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

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

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

 

Шаблоны

 

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

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

https://api.sendpulse.com/template

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

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

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

{
    "result": true,
    "real_id": 1042220
}

real_id - идентификатор шаблона, который используется для других методов, к примеру для создания рассылки.

 

Редактировать шаблон

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

https://api.sendpulse.com/template/edit/{id}

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

id идентификатор нужного шаблона загруженного в сервис. Получить ид шаблона можно при помощи метода, описанного тут (можно использовать параметры ответа real_id или id)
body верстка закодированная в base64
lang язык шаблона в двухсимвольном виде

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

 

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

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

https://api.sendpulse.com/template/{template_id}

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

template_id идентификатор шаблона. Можно получить при помощи метода, описанного тут (можно использовать параметры ответа real_id или id). Также можно взять с адресной строки в режиме редактирования шаблона после сохранения его в личном кабинете.
 

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

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

https://api.sendpulse.com/templates

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

[
{
        "id": "c7a94d4f8395ae5a4183423309d5e99b", // используется в других методах по API, преимущественно при создании рассылки. При каждом редактировании шаблона параметр меняется (!)
        "real_id": 775667, // используется для получения данных об этом одном определенном шаблоне, параметр не меняется.
        "lang": "en", 
        "name": "Nov. 9, 2018 08:24:10",
        "name_slug": "nov-9-2018-08-24-10",
        "created": "2018-11-09 05:24:10",
        "full_description": null,
        "category": "",
        "category_info": [],
        "tags": [],
        "owner": "you",
        "preview": "https://login.sendpulse.com/files/emailservice/templates/preview/e52678826db12b069358f159fde800726741804/c7a94d4f8395ae5a4183423309d5e99b.png"
    },

 {
        "id": "5979adc7712b8c822a28b486f9778a15",
        "real_id": 508742,
        "lang": "en",
        "name": "Valentine\\'s Day: sweet",
        "name_slug": "sweet-valentines-day",
        "created": "2018-02-01 08:55:04",
        "full_description": "",
        "category": "holiday",
        "category_info": {
            "id": 146,
            "name": "Holiday",
            "meta_description": "These “Holiday” free email templates were developed by SendPulse. Congratulate your customers, friends or relatives. Use these templates to create your own email campaigns in SendPulse.",
            "full_description": "",
            "code": "holiday",
            "sort": 2
        },
        "tags": {
            "valentine": "valentine"
        },
        "owner": "sendpulse",
        "preview": "https://login.sendpulse.com/files/emailservice/templates/preview/5979adc7712b8c822a28b486f9778a15_thumbnail.png"
    }
]
 

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

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

https://api.sendpulse.com/templates/?owner=sendpulse
 

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

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

https://api.sendpulse.com/templates/?owner=me
 

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

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

https://api.sendpulse.com/templates//template/slug/{name_slug}

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

name_slug системное название шаблона, найти можно в ответах апи по созданию или поиску шаблонов по другим параметрам.
 

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

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

https://api.sendpulse.com/templates/ru/?owner=me
 

Отправители

 

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

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

https://api.sendpulse.com/senders

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

[
  {
    "name": "Иван Иванов",
    "email": "JohnDoe@test.com",
    "status": "Active"
  },
  {
    "name": "Иван Иванов",
    "email": "JaneDoe@test.com",
    "status": "Active"
  }
]
 

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

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

https://api.sendpulse.com/senders

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

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

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

 

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

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

https://api.sendpulse.com/senders

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

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

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

 

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

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

https://api.sendpulse.com/senders/{email}/code

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

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

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

{
  "result": true,
  "email": JohnDoe@test.com
}
 

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

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

https://api.sendpulse.com/senders/{email}/code

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

{
  "result": true,
  "email": JohnDoe@test.com
}

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

 

Email адрес

 

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

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

https://api.sendpulse.com/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": "значение переменной"
      }
    ]
  }
]
 

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

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

https://api.sendpulse.com/emails/{email}/details

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

[
    {
        "list_name": "bookname1",
        "list_id": 1375516,
        "add_date": "2017-11-21 11:45:41",
        "source": "panel"
    },
    {
        "list_name": "bookname2",
        "list_id": 1415158,
        "add_date": "2018-01-23 07:07:08",
        "source": "panel"
    },
    {
        "list_name": "subscribers",
        "list_id": 1649207,
        "add_date": "2018-04-02 13:55:38",
        "source": "form"
    }
]

Информация по набору адресов

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

https://api.sendpulse.com/emails

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

emails массив адресов
 

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

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

https://api.sendpulse.com/campaigns/{id}/email/{email}

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

{
"sent_date": "2017-06-19 15:14:46",
"global_status": 0,
"global_status_explain": "In queue",
}

Возможные статусы можете найти вот тут

 

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

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

https://api.sendpulse.com/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://api.sendpulse.com/emails/{email}
 

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

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

https://api.sendpulse.com/emails/{email}/campaigns

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

{
  "statistic": {
    "sent": 0,
    "open": 0,
    "link": 0
  },
  "blacklist": false
}

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

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

https://api.sendpulse.com/emails/campaigns

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

emails массив адресов ["example@yourdomain.com", "example2@yourdomain.com"]

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

{
    "example@yourdomain.com": {
        "sent": 21,
        "open": 11,
        "link": 3,
        "adressbooks": [
            {
                "id": 1375516,
                "name": "book1"
            },
            {
                "id": 1415158,
                "name": "book3"
            },
            {
                "id": 1649207,
                "name": "book10"
            }
        ],
        "blacklist": false
    },
    "example2@yourdomain.com": {
        "sent": 1,
        "open": 1,
        "link": 0,
        "adressbooks": [
            {
                "id": 1734397,
                "name": "тест1"
            }
        ],
        "blacklist": true
    }
}
 

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

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

https://api.sendpulse.com/addressbooks/{addressBook_Id}/emails/variable

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

addressBook_Id ID адресной книги, в которой находится нужный имеил c переменными
email имейл получaтеля, для которого будут заменены данные
variables массив с переменными, который определяется параметрами name (название переменной) и value (значение переменной)

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

{
	"email": "myemail@example.com",
	"variables": [
		{
			"name" : "name",
			"value" : "John"
		},
		{
			"name" : "number",
			"value": 1
		},
		{
			"name": "date",
			"value" : "2019-02-01"
		},
		]
}

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

 

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

 

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

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

https://api.sendpulse.com/blacklist

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

[
  "JohnDoe@test.com",
  "JaneDoe@test.com",
]
 

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

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

https://api.sendpulse.com/blacklist

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

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

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

 

Отписать контакт в заданной адресной книге

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

https://api.sendpulse.com/addressbooks/{id}/emails/unsubscribe

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

id идентификатор адресной книги
emails контакт, который необходимо отписать от заданной книги, пример ["example@yourdomain.com"]
 


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

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

https://api.sendpulse.com/blacklist

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

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

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

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

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

 

Баланс

 

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

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

https://api.sendpulse.com/balance

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

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

https://api.sendpulse.com/balance/USD

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

{
  "currency": "USD",
  "balance_currency": 0.02
}
 

Детальная информация по балансу

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

https://api.sendpulse.com/user/balance/detail

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

{
    "balance": {
        "main": "9.36",
        "bonus": "5.00",
        "currency": "USD"
    },
    "email": {
        "tariff_name": "Пакет 10 000 писем",
        "finished_time": "2019-04-25 08:03:02",
        "emails_left": 9914,
        "maximum_subscribers": 10000,
        "current_subscribers": 0
    },
    "smtp": {
        "tariff_name": "SMTP Free",
        "end_date": "2018-11-21 15:05:39",
        "auto_renew": 1
    },
    "push": {
        "tariff_name": "White Label",
        "end_date": "2018-11-30",
        "auto_renew": 1
    }
}
 

WebHooks

Общее описание

Webhook — это механизм получения уведомлений об определенных событиях. Вы можете настроить оповещения себе в систему о доставляемости писем и активности подписчиков.

Для включения отправки автоматических вебхуков зайдите в раздел "Настройки аккаунта" -> "API" и нажмите на кнопку "Создать webhook".

Выберите событие относительно отправки письма, по которому будет срабатывать вебхук в email сервисе:

  • отмечено как спам;
  • открытие рассылки;
  • переход по ссылке;
  • новый подписчик;
  • удаление из книги;
  • пользователь отписался;
  • изменение статуса рассылки.

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

Для каждого события создается отдельный вебхук.

При срабатывании вебхука, SendPulse отправляет на указанный URL POST запрос с JSON типом данных.

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

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

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

[
  {
    "timestamp": 1496827422,
    "event": "spam",
    "task_id": 3668141,
    "email": "john.doe@sendpulse.com" 
  }
]

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

[
  {
    "task_id": 3668141,
    "timestamp": 1496827941,
    "open_device": "Desktop",
    "open_platform": "Windows",
    "browser_ver": "11.0",
    "browser_name": "Firefox",
    "email": "john.doe@sendpulse.com",
    "event": "open" 
  }
]

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

[
  {
    "link_url": http://google.com,
    "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@sendpulse.com",
    "event": "redirect" 
  }
]

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

[
  {
    "task_id": "3668141",
    "timestamp": 1496827872,
    "from_all": 1,
    "email": "john.doe@sendpulse.com",
    "reason": null,
    "book_id": 490686,
    "event": "unsubscribe",
    "categories": "" 
  }
]

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

[
  {
    "timestamp": 1496827625,
    "variables": [],
    "email": "john.doe@sendpulse.com",
    "source": "address book",
    "book_id": 490686,
    "event": "new_emails" 
  },
  {
    "timestamp": 1496827625,
    "variables": [],
    "email": "doe.john@sendpulse.com",
    "source": "subscription form",
    "book_id": 490686,
    "event": "new_emails" 
  }
]

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

[
  {
    "timestamp": 1496827422,
    "event": "delete",
    "book_id": 490686,
    "email": "john.doe@sendpulse.com" 
  }
]

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

[
  {
    "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);
?>

Также вы можете создавать, редактировать и получать информацию о вебхуках через следующие API методы:

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

Для получения списка вебхуков отправляется GET запрос по ссылке:

https://api.sendpulse.com/v2/email-service/webhook

В случае успешного запроса, сервер вернет ответ:

{
    "success": true,
    "data": [
        {
            "id": 162242,
            "user_id": 7043663,
            "url": "https://webhook.site/577e5242-bb27-4baf-8ea7-70baa6344f68",
            "action": "unsubscribe"
        },
        {
            "id": 162241,
            "user_id": 7043663,
            "url": "https://webhook.site/577e5242-bb27-4baf-8ea7-70baa6344f68",
            "action": "open"
        }
    ]
}

Получить вебхук по его ID

Для получения вебхука по его ID отправляется GET запрос по ссылке:

https://api.sendpulse.com/v2/email-service/webhook/{id}

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

id идентификатор вебхука

В случае успешного запроса, вернет ответ:

{
    "success": true,
    "data": {
        "id": 162242,
        "user_id": 7043663,
        "url": "https://webhook.site/577e5242-bb27-4baf-8ea7-70baa6344f68",
        "action": "unsubscribe"
    }
}

Создать вебхук

Для создания вебхука отправляется POST запрос по ссылке:

https://api.sendpulse.com/v2/email-service/webhook/

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

actions отслеживаемые события, пример ["open","unsubscribe"] 
url ссылка на обработчик, пример https://webhook.site/577e5242-bb27-4baf-8ea7-70baa6344f68

Возможные cобытия:

new_email новый адрес
delete удаление из книги
unsubscribe пользователь отписался
task_status_update  изменение статуса рассылки
open открытие рассылки
redirect переход по ссылке
spam отмечено как spam

Данные отправляются с типом x-www-form-urlencoded.

В случае успешного запроса, вернет ответ:

{
    "success": true,
    "data": [
        {
            "user_id": 7043663,
            "url": "https://webhook.site/577e5242-bb27-4baf-8ea7-70baa6344f68",
            "id": 162241,
            "action": "open"
        },
        {
            "user_id": 7043663,
            "url": "https://webhook.site/577e5242-bb27-4baf-8ea7-70baa6344f68",
            "id": 162242,
            "action": "unsubscribe"
        }
    ]
}

Удалить вебхук

Для удаления вебхука отправляется DELETE запрос по ссылке:

https://api.sendpulse.com/v2/email-service/webhook/{id}

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

id идентификатор вебхука

В случае успешного запроса, вернет ответ:

{
    "success": true,
    "data": [
        true
    ]
}

Обновить вебхук

Для обновления вебхука отправляется PUT запрос по ссылке:

https://api.sendpulse.com/v2/email-service/webhook/{id}

Данные отправляются с типом x-www-form-urlencoded.

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

id идентификатор вебхука
url ссылка на обработчик, пример https://webhook.site/577e5242-bb27-4baf-8ea7-70baa6344f68

В случае успешного запроса, вернет ответ:

{
    "success": true,
    "data": [
        true
    ]
}