...
Code Block |
---|
curl -X GET https://api-em.prontosms.ru/v1/email/lists?page_number=2&page_size=3 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' |
Поддерживаемые параметры
Параметр | Описание |
---|---|
page_number | Номер запрашиваемой страницы. По умолчанию: 1 |
page_size | Количество записей на странице. По умолчанию: 25 |
Если параметр page_size превышает максимально допустимый размер, то сервер ответит ошибкой со статусом 412:
...
Code Block |
---|
{ "total_count":23, "total_pages":7, "page_number":2, "page_size":3, "collection":[ { "id":1, "title":"My Recipients" }, { "id":2, "title":"My Recipients #2" }, { "id":3, "title":"My Recipients #3" } ] } |
Ключ | Описание |
---|---|
total_count | Общее количество элементов "collection" |
total_pages | Количество страниц |
page_number | Номер текущей страницы |
page_size | Количество записей на странице |
collection | Массив возвращаемых данных |
Обработка ответа
Обработка ответа может осуществляться при проверки кода состояния HTTP запроса. Так же в случае неуспешного выполнения запроса, ответ содержит массив данных c описанием ошибок в формате JSON.
...
Code Block |
---|
{ "errors":[ { "code":400, "detail":"subject is empty" } ] } |
Коды ответов
Код | Описание |
---|---|
2xx | Запрос успешно выполнен |
400 | Неверные параметры |
401 | Аутентификация не пройдена |
402 | Недостаточно средств |
404 | Ресурс не найден |
415 | Неподдерживаемый тип данных |
422 | Ресурс не может быть обработан |
Ограничения на количество запросов
...
POST /email/messages
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
from_email | Да | |
from_name | ||
to | Да | |
subject | Да | |
text | Должен присутствовать хотя бы один параметр: | |
html | Должен присутствовать хотя бы один параметр: | |
attachments | Массив с вложениями. Поддерживается только для запросов с типом содержимого multipart/form-data | |
payment | Способ тарификации сообщения. Возможные значения: |
Способы тарификации сообщения
Значение | Описание |
---|---|
subscriber_priority | Тарифицируется "подписчик", если не доступны "подписчики", используется "письмо". Если нет "писем", возвращается ошибка. |
credit_priority | Тарифицируется "письмо". Если нет "писем", используется "подписчик". Если нет "подписчиков", возвращается ошибка. |
subscriber | Тарифицируется "подписчик". Если нет "подписчиков", возвращается ошибка. |
credit | Тарифицируется "письмо". Если нет "писем", возвращается ошибка. |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор сообщения |
from_email | Адрес отправителя |
from_name | Имя отправителя |
to | Адрес получателя |
subject | Тема |
text | Текстовая версия сообщения |
html | HTML версия сообщения |
attachments | Массив имен вложенных файлов |
status | Статус сообщения |
events | Информация о событиях |
Статусы сообщения
Статус | Описание |
---|---|
queued | Принято в очередь |
sent | Отправлено. Ожидается подтверждение доставки. |
delivered | Доставлено |
skipped | Не отправлено |
soft_bounced | Сообщение не доставлено |
hard_bounced | Сообщение не может быть доставлено |
Информация о событиях
Событие | Описание |
---|---|
open | Сообщение прочитано |
redirect | Получатель перешел по ссылке |
spam | Сообщение помечено как спам |
unsubscribe | Пользователь отписался |
Обратите внимание на то, что при отправке сообщений сервер может вернуть ответ со статусом 429. Это означает, что вы превысили количество сообщений, разрешенное к отправке, в единицу времени. Результат отправки сообщений влияет на лимит сообщений в единицу времени. Таким образом, если вы отправляете письма только вашим клиентам, только на существующие адреса, не рассылаете спам и тп, то разрешенное количество сообщений в единицу времени для вашего аккаунта будет увеличиваться, и наоборот.
...
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
from_email | Адрес отправителя |
from_name | Имя отправителя |
to | Адрес получателя |
subject | Тема |
text | Текстовая версия сообщения |
html | HTML версия сообщения |
status | Статус сообщения |
events | Информация о событиях |
Статусы сообщения
Статус | Описание |
---|---|
queued | Принято в очередь |
sent | Отправлено |
delivered | Доставлено |
skipped | Не отправлено |
soft_bounced | Сообщение не доставлено |
hard_bounced | Сообщение не может быть доставлено |
Информация о событиях
Событие | Описание |
---|---|
open | Сообщение прочитано |
redirect | Получатель перешел по ссылке |
spam | Сообщение помечено как спам |
unsubscribe | Пользователь отписался |
Отправка одиночного сообщения по шаблону
...
где :template_id - идентификатор шаблона
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
to | email получателя | Да |
params | Параметры подстановки | Нет |
payment | Способ тарификации сообщения. Возможные значения: | Нет |
Способы тарификации сообщения
Значение | Описание |
---|---|
subscriber_priority | Тарифицируется "подписчик", если не доступны "подписчики", используется "письмо". Если нет "писем", возвращается ошибка. |
credit_priority | Тарифицируется "письмо". Если нет "писем", используется "подписчик". Если нет "подписчиков", возвращается ошибка. |
subscriber | Тарифицируется "подписчик". Если нет "подписчиков", возвращается ошибка. |
credit | Тарифицируется "письмо". Если нет "писем", возвращается ошибка. |
Пример запроса
Code Block |
---|
curl -X POST https://api-em.prontosms.ru/v1/email/templates/1/messages \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' \ -d '...JSON...' |
...
POST /email/lists
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
title | Название группы получателей. Должно быть уникальным | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор созданной группы |
title | Название группы |
Получение списка групп
Пример запроса
...
Ответ сервера содержит коллекцию групп получателей. Каждый элемент содержит следующие атрибуты:
Атрибут | Описание |
---|---|
id | Идентификатор группы |
title | Название группы |
Получение информации о группе
...
Ответ сервера в формате JSON содержит следующие атрибуты:
Атрибут | Описание |
---|---|
id | Идентификатор группы |
title | Название группы |
Удаление группы
Пример запроса
...
где :id - идентификатор группы для запроса информации
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
title | Название группы получателей. Должно быть уникальным | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор созданной группы |
title | Название группы |
Параметры группы получателей
...
POST /email/lists/:id/parameters
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
title | Да | |
kind | Возможные значения: |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
title | Название |
kind | Тип |
Список параметров
Пример запроса
...
Ответ сервера содержит коллекцию параметров группы получателей. Каждый элемент содержит следующие атрибуты:
Атрибут | Описание |
---|---|
id | Идентификатор |
title | Название |
kind | Тип |
Изменение параметра
Пример JSON для запроса
...
где :list-id - идентификатор группы, :id - идентификатор параметра
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
title | ||
kind | Возможные значения: |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
title | Название |
kind | Тип |
Удаление параметра
Пример запроса
...
POST /email/lists/:id/recipients
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
Да | ||
unconfirmed | Создать неподтвержденного получателя. Необходимо задать любое значение, например, true, t или 1. По умолчанию создается подтвержденный получатель | Нет |
values | Массив значений для параметров |
Элементы массива значений
Параметр | Описание | Обязательный |
---|---|---|
parameter_id | ID параметра группы получателей | Да |
value | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
Адрес | |
confirmed | Подтвержден получатель или нет |
values | Массив значений |
Элементы массива значений
Параметр | Описание |
---|---|
parameter_id | ID параметра группы получателей |
kind | Тип параметра |
value | Значение |
Обновление получателя
Пример JSON для запроса
...
PATCH /email/lists/:list_id/recipients/:id
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
Нет | ||
values | Массив значений для параметров |
Элементы массива значений
Параметр | Описание | Обязательный |
---|---|---|
parameter_id | ID параметра группы получателей | Да |
value | Не может быть одновременно использован с параметром destroy | Нет |
destroy | Используется для удаления значения. Для удаления значения необходимо задать любое значение, например, true, t или 1. Не можеть быть использован одновременно с параметром value | Нет |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
Адрес | |
confirmed | Подтвержден получатель или нет |
values | Массив значений |
Элементы массива значений
Параметр | Описание |
---|---|
parameter_id | ID параметра группы получателей |
kind | Тип параметра |
value | Значение |
Список получателей
Пример запроса
...
Ответ сервера содержит коллекцию получателей в группе. Каждый элемент содержит следующие атрибуты:
Атрибут | Описание |
---|---|
id | Идентификатор |
Адрес | |
confirmed | Подтвержден получатель или нет |
values | Массив значений |
Элементы массива значений
Параметр | Описание |
---|---|
parameter_id | ID параметра группы получателей |
kind | Тип параметра |
value | Значение |
Удаление получателя
Пример запроса
...
POST /email/lists/:id/recipients/imports
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
recipients | Массив получателей. Максимальный размер 10000 | Да |
run_triggers | Запустить связанные триггеры. Необходимо задать любое значение, например, true, t или 1. | Нет |
tags | Массив значений тегов | Нет |
callback_url | url, на который будет отправлен запрос после завершения импорта | нет |
Массив получателей recipients
Параметр | Описание | Обязательный |
---|---|---|
Email получателя | Да | |
values | Массив значений |
параметров | Нет |
Элементы массива значений values
Параметр | Описание | Обязательный |
---|---|---|
parameter_id | ID параметра группы получателей | Да |
value | Значение параметра | Да |
Ответ сервера
Параметр | Описание |
---|---|
id | Идентификатор импорта. В дальнейшем может использоваться для получения информации о ходе импорта |
status | Статус импорта |
callback_url | url, на который будет отправлен запрос после окончании импорта |
Пример JSON для запроса
Code Block |
---|
{ "recipients":[ { "email":"alice@example.org", "values":[ { "parameter_id":"1", "value":"Alice" }, { "parameter_id":"2", "value":"22" } ] }, { "email":"bob@example.org", "values":[ { "parameter_id":"1", "value":"Bob" }, { "parameter_id":"2", "value":"11" } ] } ], "tags":[ "buyer", "regular customer" ] } |
Пример запроса
Code Block |
---|
curl -X POST https://api-em.prontosms.ru/v1/email/lists/1/recipients/imports \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' \ -d '...JSON...' |
...
Code Block |
---|
{ "id":7, "status":"queued", "callback_url": null } |
Пример запроса после окончания импорта, если указан callback url
Code Block |
---|
{ "id":7, "status":"completed", "callback_url":"https://my-callback-url.com/some-secret" } |
Поиск получателей
Данный метод позволяет осуществить поиск получателя по email, например, чтобы определить в каких группах есть данный получатель.
...
GET /email/recipients/search
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
Искомый адрес | Да |
Ответ сервера
Ответ сервера содержит коллекцию получателей в группе. Каждый элемент содержит следующие атрибуты:
Атрибут | Описание |
---|---|
Адрес получателя | |
recipients | Массив, содержащий информацию о списках, в которых есть искомый получатель |
Организации
Создание организации
...
POST /email/organizations
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
name | Да | |
address | Да | |
country | Да | |
city | Да | |
phone | Да | |
zip | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Список организаций
Пример запроса
...
Ответ сервера содержит коллекцию организаций. Каждый элемент содержит следующие атрибуты:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Информация об организации
...
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Организация по умолчанию
Пример запроса
...
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Задать организацию по умолчанию
...
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Изменение организации
Пример JSON для запроса
...
PATCH /email/organizations/:id
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
name | ||
address | ||
country | ||
city | ||
phone | ||
zip |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Удаление организации
Пример запроса
...
POST /email/campaigns
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
from_email | Да | |
subject | Да | |
from_name | ||
text | Должен присутствовать хотя бы один параметр: | |
html | Должен присутствовать хотя бы один параметр: | |
lists | Массив групп получателей | Да |
Элементы массива групп получателей
Параметр | Описание | Обязательный |
---|---|---|
id | ID группы получателей | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
from_email | Адрес отправителя |
from_name | Имя отправителя |
html | |
text | |
state | Статус |
recipients_count | Количество получателей |
purchase | Информация о тарификации |
statistics | Статистика |
Статусы
Значение | Описание |
---|---|
draft | Черновик |
pending | На модерации |
delayed | Запланированная |
sending | Отправляется |
canceled | Отменена |
stopped | Остановлена |
completed | Завершена |
archived | В архиве |
Информация о тарификации
Атрибут | Описание |
---|---|
enable | Может принимать значение true (отправка возможна) или false (недостаточно средств) |
subscribers | Количество подписчиков которое будет списано |
credits | Количество кредитов которое будет списано |
deficit | Количество недостающих средств |
Статистика
Атрибут | Описание |
---|---|
delivered | Количество доставленных сообщений |
bounced | Количество недоставленный сообщений |
delivering | Количество доставляющихся сообщений |
uniq_open | Количество уникальных открытий |
uniq_click | Количество уникальных переходов |
unsubscription | Количество отписок |
spam | Количество нажатий кнопки "спам" |
Отправка рассылки
Пример запроса
...
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
from_email | Адрес отправителя |
from_name | Имя отправителя |
html | |
text | |
state | Статус |
recipients_count | Количество получателей |
purchase | Информация о тарификации |
statistics | Статистика |
Статусы
Значение | Описание |
---|---|
draft | Черновик |
pending | На модерации |
delayed | Запланированная |
sending | Отправляется |
canceled | Отменена |
stopped | Остановлена |
completed | Завершена |
archived | В архиве |
Информация о тарификации
Атрибут | Описание |
---|---|
enable | Может принимать значение true (отправка возможна) или false (недостаточно средств) |
subscribers | Количество подписчиков которое будет списано |
credits | Количество кредитов которое будет списано |
deficit | Количество недостающих средств |
Статистика
Атрибут | Описание |
---|---|
delivered | Количество доставленных сообщений |
bounced | Количество недоставленный сообщений |
delivering | Количество доставляющихся сообщений |
uniq_open | Количество уникальных открытий |
uniq_click | Количество уникальных переходов |
unsubscription | Количество отписок |
spam | Количество нажатий кнопки "спам" |
Информация о рассылке
Пример запроса
...
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
from_email | Адрес отправителя |
from_name | Имя отправителя |
html | |
text | |
state | Статус |
recipients_count | Количество получателей |
purchase | Информация о тарификации |
statistics | Статистика |
Статусы
Значение | Описание |
---|---|
draft | Черновик |
pending | На модерации |
delayed | Запланированная |
sending | Отправляется |
canceled | Отменена |
stopped | Остановлена |
completed | Завершена |
archived | В архиве |
Информация о тарификации
Атрибут | Описание |
---|---|
enable | Может принимать значение true (отправка возможна) или false (недостаточно средств) |
subscribers | Количество подписчиков которое будет списано |
credits | Количество кредитов которое будет списано |
deficit | Количество недостающих средств |
Статистика
Атрибут | Описание |
---|---|
delivered | Количество доставленных сообщений |
bounced | Количество недоставленный сообщений |
delivering | Количество доставляющихся сообщений |
uniq_open | Количество уникальных открытий |
uniq_click | Количество уникальных переходов |
unsubscription | Количество отписок |
spam | Количество нажатий кнопки "спам" |
Webhooks
Данный механизм позволяют получать POST запросы на указанный URL, когда происходят события, связанные с одиночными сообщениями.
...
Ключ message содержит информацию о сообщении, с которым связано событие. Ключ event содержит информацию о событии. На данный момент ключ data возвращается только для события clicked, и содержит адрес ссылки, по которой кликнули.
Виды событий
Событие | Описание |
---|---|
delivered | Сообщение доставлено |
opened | Сообщение открыто |
clicked | Получатель перешел по ссылке. Ключ event.data содержит URL ссылки |
unsubscribed | Получатель отписался |
complined | Получатель пожаловался на спам |
skipped | Сообщение не было отправлено (возможные причины: получатель ранее отписался или пожаловался на спам) |
soft_bounced | Сообщение не принято почтовым сервером получателя (возможно, будет принято позже) |
hard_bounced | Сообщение не принято почтовым сервером получателя |
Установка webhook
Пример JSON для запроса
...
POST /email/webhook
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
url | URL, на который отправлять данные о событии | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
url | URL, на который отправлять данные о событии |
Получение информации о webhook
...