Описание API

Вступление

API интерфейс используется для того, чтобы интегрировать возможности сервиса рассылок SendPulse в личный проект клиента. API предназначен для разработчиков и сопровождается детальной документацией.

Описание

REST API сервиса SendPulse работает по протоколу HTTPS и представляет собой набор методов, с помощью которых совершаются запросы и возвращаются ответы для каждой операции. Все ответы приходят в виде JSON структур.

Ограничение на количество запросов - 10 запросов в секунду.

Кросдоменные запросы (например, jQuery Ajax) запрещены.

Библиотеки API

Актуальные версии библиотек API на GitHub доступны по ссылкам:

• PHP wrapper
• Python wrapper
• Ruby wrapper
• Java wrapper
• Node.js wrapper
• C# wrapper 
• Go wrapper (стороннее решение)

Также вы можете посмотреть другие сторонние решения на Github.

Основной URL

Все ссылки на запросы к API в данной документации включают обязательный основной URL:

https://api.sendpulse.com

Авторизация

Процесс авторизации возможен при наличии персонального ключа (токена), которым в дальнейшем должен быть подписан каждый запрос к API.
Код ключа (токен) передается в заголовке любого запроса (в "headers") кроме случаев получения самого токена, когда этот код не требуется.

Необходимые для получения ключа параметры можно найти в настройках аккаунта, во вкладке API.

Для получения ключа отправьте POST запрос по ссылке:

https://api.sendpulse.com/oauth/access_token

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

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

{
   "grant_type":"client_credentials",
   "client_id":"237b4af9c99d0f89bdbd876dcd5a0000",
   "client_secret":"a99e7d506d3701c5c04de3db1913eeee"
}

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

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjI5NTQ4NDVjZWJlZjg5Nzk0YmYzMzk4ZDdiNTQ3OTA2MWUzNDQ2N2I5NTUwMmFlNzE1YmViZmU4MDBmNTMxMjIxMTU2MTcyOWM2MjI5NGRjIn0.eyJhdWQiOiIyMzdiNGFmOWM5OWQwZjg5YmRiZDg3NmRjZDVhMDE3ZiIsImp0aSI6IjI5NTQ4NDVjZWJlZjg5Nzk0YmYzMzk4ZDdiNTQ3OTA2MWUzNDQ2N2I5NTUwMmFlNzE1YmViZmU4MDBmNTMxMjIxMTU2MTcyOWM2MjI5NGRjIiwiaWF0IjaaNjI0NTI0OTA0LCJuYmYiOjE2MjQ1MjQ5MDQsImV4cCI6MTYyNDUyODUwNCwic3ViIjoiIiwic2NvcGVzIjpbXSwidXNlciI6eyJpZCI6Njc0MTgwNCwiZ3JvdXBfaWQiOm51bGwsInBhcmVudF9pZCI6bnVsbCwiYXJlYSI6InJlc3QifX0.jiP3Sv7IF1mHGmW0oGIrPAw0oOiIEnC8Tb6wlWu5eVM2UrHL6RZsDlIslLSQNEvL_e50nDlgtgyfX5Qty4qlQ4XyW53FAgjwHbyQG7DJ6iVRAtVBtFNbkFVNbHvKw8zQy7WyxhICpAF8zdF8-gBHBnzuMhKSnASYEosJ9IAPqUkxQXrd8LpUSk-etzjEqcpMkbGj2M7Y0OxO4_BfRhVNU6ZcbiawD09m0A9uWoSnoZKxXw0o64PE3anJta6lFns5SDuyeGxanOtuZSS5I3umI2OOnUVzNG9_5WjCe6LPVQLAPAPt0m8S5WkI35_jCJ0A-gDBBdsgnUudGCvsDcgEog",
  "token_type": "Bearer",
  "expires_in": 3600
}

Пример ключа в header для авторизации API запросов:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjI5NTQ4NDVjZWJlZjg5Nzk0YmYzMzk4ZDdiNTQ3OTA2MWUzNDQ2N2I5NTUwMmFlNzE1YmViZmU4MDBmNTMxMjIxMTU2MTcyOWM2MjI5NGRjIn0.eyJhdWQiOiIyMzdiNGFmOWM5OWQwZjg5YmRiZDg3NmRjZDVhMDE3ZiIsImp0aSI6IjI5NTQ4NDVjZWJlZjg5Nzk0YmYzMzk4ZDdiNTQ3OTA2MWUzNDQ2N2I5NTUwMmFlNzE1YmViZmU4MDBmNTMxMjIxMTU2MTcyOWM2MjI5NGRjIiwiaWF0IjaaNjI0NTI0OTA0LCJuYmYiOjE2MjQ1MjQ5MDQsImV4cCI6MTYyNDUyODUwNCwic3ViIjoiIiwic2NvcGVzIjpbXSwidXNlciI6eyJpZCI6Njc0MTgwNCwiZ3JvdXBfaWQiOm51bGwsInBhcmVudF9pZCI6bnVsbCwiYXJlYSI6InJlc3QifX0.jiP3Sv7IF1mHGmW0oGIrPAw0oOiIEnC8Tb6wlWu5eVM2UrHL6RZsDlIslLSQNEvL_e50nDlgtgyfX5Qty4qlQ4XyW53FAgjwHbyQG7DJ6iVRAtVBtFNbkFVNbHvKw8zQy7WyxhICpAF8zdF8-gBHBnzuMhKSnASYEosJ9IAPqUkxQXrd8LpUSk-etzjEqcpMkbGj2M7Y0OxO4_BfRhVNU6ZcbiawD09m0A9uWoSnoZKxXw0o64PE3anJta6lFns5SDuyeGxanOtuZSS5I3umI2OOnUVzNG9_5WjCe6LPVQLAPAPt0m8S5WkI35_jCJ0A-gDBBdsgnUudGCvsDcgEog

Ограничения запросов

При использовании SendPulse API есть лимиты и квоты на количество запросов. Ограничения нужны, чтобы защитить систему от получения большего количества данных, чем она может обработать, а также обеспечить распределение системных ресурсов. Лимиты на использование API в минуту и сутки зависят от категории тарифного плана, который подключил пользователь.

Общие лимиты квот

В таблице приводим ограничения, которые применяются на отправку запросов к API.

Превышение лимитов квот

Если вы превысите лимиты, API вернет следующую ошибку:

429 Too many requests

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

Коды ошибок и их описание

Код ошибки	Описание
8	Отсутствуют данные
10	Отсутствует e-mail адрес отправителя
11	Не указаны получатели
13	Отсутствует контент email сообщения
14	Email адрес с заданным значением ID не найден
17	Email адрес не найден
19	Такой email адрес уже существует
20	Пожалуйста, не используйте бесплатные почтовые сервисы
21	На активации нет указанного email адреса
97	Недопустимый тип email адреса. Использовать аккаунты бесплатных почтовых сервисов не рекомендуется.
201	Отсутствует название адресной книги
203	Адресная книга с указанным именем уже существует
211	Адресная книга пуста
213	Адресная книга не найдена.
303	Отсутствуют email адреса в адресной книге
400	Не существует такого пользователя SMTP. Вам необходимо создать аккаунт в SMTP сервисе.
502	Не найден email адрес
602	Кампания не найдена. Возможно, она была уже отправлена.
701	Отсутствует email адрес или имя отправителя
703	Не найдена адресная книга
704	Не найден отправитель
707	Недостаточно средств на счету
711	Вам следует подождать 15 минут перед повторной попыткой отправки на данную адресную книгу
720	Не указана тема письма
721	Отсутствует контент email сообщения
722	Не указано ID адресной книги
791	Лимит API-кампаний (5 в час) превышен
799	Неправильный формат даты. Должен быть в формате Y-m-d H:i:s и не может быть меньше текущей даты
800	Недопустимое действие
802	Кампания не найдена
901	Не указано имя отправителя
902	Выбранный email адрес уже занят
903	Не указан email адрес отправителя
904	Email адрес найден в черном списке
905	Достигнут лимит доступного количества адресов отправителя
906	Ошибка в email адресе
1101	Не указан email адрес
1003	Указанного отправителя не существует
1004	Код активации был отправлен. Вам следует подождать 15 минут перед повторной попыткой.
1005	Ошибка при отправке подтверждения
1104	Отсутствует код активации
2020202020	Более 10 запросов в секунду