API для email рассылок - API документация

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

Путем использования 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

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

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

В случае успеха сервер вернет 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_emails	новый адрес
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
    ]
}