Общие сведения
Данный документ содержит сведения о программном интерфейсе сервиса email рассылок (далее - «API»). Через API внешние приложения получают доступ к системе управлению списками получателей, отправке одиночных email сообщений, рассылок, а также прочий функционал для работы со списками получателей и статистикой рассылок.
Регистрация и вход в личный кабинет доступны по ссылке: app.prontosms.ru.
Базовый URL
Базовый URL для всех запросов
https://api-em.prontosms.ru/v1
Аутентификация
Для удостоверения подлинности запросов, в каждом обращении к API необходимо отправлять заголовок содержащий Ваш ключ.
Authorization: Bearer $API_TOKEN
Ключ для доступа к API можно получить в личном кабинете.
Держите Ваш ключ для доступа к API в секрете.
Формат обмена данных
Для обмена данными используется формат JSON, поэтому, в каждом запросе должен присутствовать заголовок
Content-Type: application/json
Все данные от сервера возвращаются так же, в формате JSON.
Получение списков данных (Collection)
Списки данных (Collection) - постраничный способ выдачи данных, используемый в некоторых методах Для управления страницами выдачи списка данных в заголовках запроса необходимо передавать параметры:
Пример запроса
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:
{ "errors": [ { "code": 412, "detail": "Page size is too big. Max value is 100" } ] }
По умолчанию максимальный page_size равняется 100, если в описании конкретного метода не указано другое.
При выполнении запроса с использованием списка данных ответ будет возвращен в виде структуры:
Пример ответа со списком данных (Collection)
{ "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.
Пример ответа с ошибками
{ "errors":[ { "code":400, "detail":"subject is empty" } ] }
Коды ответов
Код | Описание |
---|---|
2xx | Запрос успешно выполнен |
400 | Неверные параметры |
401 | Аутентификация не пройдена |
402 | Недостаточно средств |
404 | Ресурс не найден |
415 | Неподдерживаемый тип данных |
422 | Ресурс не может быть обработан |
Ограничения на количество запросов
На данный момент есть ограничение в 5 запросов в секунду на любые запросы, кроме запросов типа GET. В случае превышения ограничения сервер вернет ответ со статусом 429.
Одиночные сообщения
Отправка одиночного email сообщения
Пример JSON для запроса
{ "from_email":"alice@example.org", "from_name": "Alice", "to": "bob@example.org", "subject": "Hello", "text": "Hello, Bob!", "html": "<h1>Hello, Bob!</h1>", "payment": "credit" }
Пример запроса
curl -X POST https://api-em.prontosms.ru/v1/email/messages \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' \ -d '...JSON...'
Пример ответа в случае успеха
{ "id":1, "from_email":"alice@example.org", "from_name":"Alice", "to":"bob@example.org", "subject":"Hello", "text":"Hello, Bob!", "html":"<h1>Hello, Bob!</h1>", "attachments": [], "status":"queued", "events": { "open": 1, "redirect": { "http://foo.com": 2, "http://bar.com": 3 }, "spam": 1, "unsubscribe": 1 } }
Пример запроса для отправки сообщения с вложениями
curl -X POST https://api-em.prontosms.ru/v1/email/messages \ -H 'Authorization: Bearer $API_TOKEN' \ -F from_email=from@example.com \ -F to=to@example.com \ -F subject='Mail with attachments' \ -F text='Hello world' \ -F attachments[]=@/path/to/file1 \ -F attachments[]=@/path/to/file2
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. Это означает, что вы превысили количество сообщений, разрешенное к отправке, в единицу времени. Результат отправки сообщений влияет на лимит сообщений в единицу времени. Таким образом, если вы отправляете письма только вашим клиентам, только на существующие адреса, не рассылаете спам и тп, то разрешенное количество сообщений в единицу времени для вашего аккаунта будет увеличиваться, и наоборот.
Получение информации о сообщении
Пример запроса
curl -X GET https://api-em.prontosms.ru/v1/email/messages/1 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' \ -d '...JSON...'
Пример ответа в случае успеха
{ "id":1, "from_email":"alice@example.org", "from_name":"Alice", "to":"bob@example.org", "subject":"Hello", "text":"Hello, Bob!", "html":"<h1>Hello, Bob!</h1>", "status":"queued", "events": { "open": 1, "redirect": { "http://foo.com": 2, "http://bar.com": 3 }, "spam": 1, "unsubscribe": 1 } }
GET /email/messages/:id
Ответ сервера
Ответ сервера содержит 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 | Пользователь отписался |
Отправка одиночного сообщения по шаблону
В личном кабинете в разделе "Автоматизация", выберите "Одиночное по шаблону" и создайте шаблон письма. Отправляйте письма по этому шаблону с параметрами. Для подстановки параметра в шаблоне используйте конструкцию [%имя параметра%], например [%name%], [%age%] и т.д.
Пример JSON для запроса
{ "to": "bob@example.org", "payment": "credit", "params": { "name": "Ivan", "age": "33" } }
POST /email/templates/:template_id/messages
где :template_id - идентификатор шаблона
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
to | email получателя | Да |
params | Параметры подстановки | Нет |
payment | Способ тарификации сообщения. Возможные значения: | Нет |
Способы тарификации сообщения
Значение | Описание |
---|---|
subscriber_priority | Тарифицируется "подписчик", если не доступны "подписчики", используется "письмо". Если нет "писем", возвращается ошибка. |
credit_priority | Тарифицируется "письмо". Если нет "писем", используется "подписчик". Если нет "подписчиков", возвращается ошибка. |
subscriber | Тарифицируется "подписчик". Если нет "подписчиков", возвращается ошибка. |
credit | Тарифицируется "письмо". Если нет "писем", возвращается ошибка. |
Пример запроса
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...'
Группы получателей
Создание группы
Пример JSON для запроса
{ "title":"My Recipients" }
Пример запроса
curl -X POST https://api-em.prontosms.ru/v1/email/lists \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' \ -d '...JSON...'
Пример ответа в случае успеха
{ "id":1, "title":"My Recipients" }
POST /email/lists
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
title | Название группы получателей. Должно быть уникальным | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор созданной группы |
title | Название группы |
Получение списка групп
Пример запроса
curl -X GET https://api-em.prontosms.ru/v1/email/lists \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'
Данный метод поддерживает постраничную выдачу результатов.
Пример ответа в случае успеха
{ "total_count":3, "total_pages":1, "page_number":1, "page_size":25, "collection":[ { "id":1, "title":"My Recipients" }, { "id":2, "title":"My Recipients #2" }, { "id":3, "title":"My Recipients #3" } ] }
GET /email/lists
Ответ сервера
Ответ сервера содержит коллекцию групп получателей. Каждый элемент содержит следующие атрибуты:
Атрибут | Описание |
---|---|
id | Идентификатор группы |
title | Название группы |
Получение информации о группе
Пример запроса
curl -X GET https://api-em.prontosms.ru/v1/email/lists/1 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{ "id":1, "title":"My Recipients" }
GET /email/lists/:id
где :id - идентификатор группы для запроса информации
Ответ сервера
Ответ сервера в формате JSON содержит следующие атрибуты:
Атрибут | Описание |
---|---|
id | Идентификатор группы |
title | Название группы |
Удаление группы
Пример запроса
curl -X DELETE https://api-em.prontosms.ru/v1/email/lists/1 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'
DELETE /email/lists/:id
где :id - идентификатор группы для запроса информации
Ответ сервера
В случае успешного удаления сервер вернет пустой ответ со статусом 204.
Редактирование группы
Пример JSON для запроса
{ "title":"New Title" }
Пример запроса
curl -X PATCH https://api-em.prontosms.ru/v1/email/lists/1 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' -d '...JSON...'
Пример ответа в случае успеха
{ "id":1, "title":"New Title" }
PATCH /email/lists/:id
где :id - идентификатор группы для запроса информации
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
title | Название группы получателей. Должно быть уникальным | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор созданной группы |
title | Название группы |
Параметры группы получателей
Создание параметра
Пример JSON для запроса
{ "title":"Age", "kind": "numeric" }
Пример запроса
curl -X POST https://api-em.prontosms.ru/v1/email/lists/1/parameters \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' \ -d '...JSON...'
Пример ответа в случае успеха
{ "id":11, "title":"Age", "kind":"numeric", "list_id":15 }
POST /email/lists/:id/parameters
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
title | Да | |
kind | Возможные значения: |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
title | Название |
kind | Тип |
Список параметров
Пример запроса
curl -X GET https://api-em.prontosms.ru/v1/email/lists/1/parameters \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'
Данный метод поддерживает постраничную выдачу результатов.
Пример ответа в случае успеха
{ "total_count":2, "total_pages":1, "page_number":1, "page_size":25, "collection":[ { "id":1, "title":"Name", "kind":"string", "list_id":1 }, { "id":2, "title":"Age", "kind":"numeric", "list_id":1 } ] }
GET /email/lists/:id/parameters
Ответ сервера
Ответ сервера содержит коллекцию параметров группы получателей. Каждый элемент содержит следующие атрибуты:
Атрибут | Описание |
---|---|
id | Идентификатор |
title | Название |
kind | Тип |
Изменение параметра
Пример JSON для запроса
{ "title":"Age", "kind": "numeric" }
Пример запроса
curl -X PATCH https://api-em.prontosms.ru/v1/email/lists/11/parameters/15 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' \ -d '...JSON...'
Пример ответа в случае успеха
{ "id":11, "title":"Age", "kind":"numeric", "list_id":15 }
PATCH /email/lists/:list-id/parameters/:id
где :list-id - идентификатор группы, :id - идентификатор параметра
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
title | ||
kind | Возможные значения: |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
title | Название |
kind | Тип |
Удаление параметра
Пример запроса
curl -X DELETE https://api-em.prontosms.ru/v1/email/lists/11/parameters/15 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'
DELETE /email/lists/:list-id/parameters/:id
где :list-id - идентификатор группы, :id - идентификатор параметра
Получатели
Создание получателя
Пример JSON для запроса
{ "email":"alice@example.org", "unconfirmed": true, "values":[ { "parameter_id":"1", "value":"Alice" }, { "parameter_id":"2", "value":"22" } ] }
Пример запроса
curl -X POST https://api-em.prontosms.ru/v1/email/lists/1/recipients \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' \ -d '...JSON...'
Пример ответа в случае успеха
{ "id":1, "email":"alice@example.org", "confirmed":false, "list_id":1, "values":[ { "value":"Alice", "kind":"string", "parameter_id":1 }, { "value":22.0, "kind":"numeric", "parameter_id":2 } ] }
POST /email/lists/:id/recipients
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
Да | ||
unconfirmed | Создать неподтвержденного получателя. Необходимо задать любое значение, например, true, t или 1. По умолчанию создается подтвержденный получатель | Нет |
values | Массив значений для параметров |
Элементы массива значений
Параметр | Описание | Обязательный |
---|---|---|
parameter_id | ID параметра группы получателей | Да |
value | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
Адрес | |
confirmed | Подтвержден получатель или нет |
values | Массив значений |
Элементы массива значений
Параметр | Описание |
---|---|
parameter_id | ID параметра группы получателей |
kind | Тип параметра |
value | Значение |
Обновление получателя
Пример JSON для запроса
{ "email":"alice@example.org", "values":[ { "parameter_id":"1", "value":"Alice" }, { "parameter_id":"2", "destroy":"true" } ] }
Пример запроса
curl -X PATCH https://api-em.prontosms.ru/v1/email/lists/1/recipients/1 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' \ -d '...JSON...'
Пример ответа в случае успеха
{ "id":1, "email":"alice@example.org", "confirmed":true, "list_id":1, "values":[ { "value":"Alice", "kind":"string", "parameter_id":1 } ] }
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 | Значение |
Список получателей
Пример запроса
curl -X GET https://api-em.prontosms.ru/v1/email/lists/1/recipients \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'
Данный метод поддерживает постраничную выдачу результатов. Максимальный page_size равняется 1000.
Пример ответа в случае успеха
{ "total_count":2, "total_pages":1, "page_number":1, "page_size":25, "collection":[ { "id":1, "email":"alice@example.org", "confirmed":true, "list_id":1, "values":[ { "value":"Alice", "kind":"string", "parameter_id":9 }, { "value":22.0, "kind":"numeric", "parameter_id":10 } ] }, { "id":2, "email":"bob@example.org", "confirmed":true, "list_id":1, "values":[ ] } ] }
GET /email/lists/:id/recipients
Ответ сервера
Ответ сервера содержит коллекцию получателей в группе. Каждый элемент содержит следующие атрибуты:
Атрибут | Описание |
---|---|
id | Идентификатор |
Адрес | |
confirmed | Подтвержден получатель или нет |
values | Массив значений |
Элементы массива значений
Параметр | Описание |
---|---|
parameter_id | ID параметра группы получателей |
kind | Тип параметра |
value | Значение |
Удаление получателя
Пример запроса
curl -X DELETE https://api-em.prontosms.ru/v1/email/lists/1/recipients/1 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'
DELETE /email/lists/:list_id/recipients/:id
Импорт большого количества получателей
POST /email/lists/:id/recipients/imports
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
recipients | Массив получателей. Максимальный размер 10000 | Да |
run_triggers | Запустить связанные триггеры. Необходимо задать любое значение, например, true, t или 1. | Нет |
Массив получателей
Параметр | Описание | Обязательный |
---|---|---|
Да | ||
values | Массив значений для параметров |
Элементы массива значений
Параметр | Описание | Обязательный |
---|---|---|
parameter_id | ID параметра группы получателей | Да |
value | Да |
Ответ сервера
Параметр | Описание |
---|---|
id | Идентификатор импорта. В дальнейшем может использоваться для получения информации о ходе импорта |
status | Статус импорта |
Пример JSON для запроса
{ "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" } ] } ] }
Пример запроса
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...'
Пример ответа в случае успеха
{ "id":7, "status":"queued" }
Поиск получателей
Данный метод позволяет осуществить поиск получателя по email, например, чтобы определить в каких группах есть данный получатель.
Пример запроса
curl -X GET https://api-em.prontosms.ru/v1/email/recipients/search?email=foo@bar.com \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{ "total_count": 2, "total_pages": 1, "page_number": 1, "page_size": 25, "collection": [ { "email": "foo@bar.com", "recipients": [ { "list_id": 1, "list_title": "List #1", "recipient_id": 1 }, { "list_id": 2, "list_title": "List #2", "recipient_id": 2 } ] } ], "query": "test" }
GET /email/recipients/search
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
Искомый адрес | Да |
Ответ сервера
Ответ сервера содержит коллекцию получателей в группе. Каждый элемент содержит следующие атрибуты:
Атрибут | Описание |
---|---|
Адрес получателя | |
recipients | Массив, содержащий информацию о списках, в которых есть искомый получатель |
Организации
Создание организации
Пример JSON для запроса
{ "name":"My Organization", "address":"Lenina 40", "country":"Russia", "city":"Tomsk", "phone":"+7-3822-123-456", "zip":"634000" }
Пример запроса
curl -X POST https://api-em.prontosms.ru/v1/email/organizations \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' \ -d '...JSON...'
Пример ответа в случае успеха
{ "id":1, "name":"My Organization", "address":"Lenina 40", "country":"Russia", "city":"Tomsk", "phone":"+7-3822-123-456", "zip":"634000", "current":true }
POST /email/organizations
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
name | Да | |
address | Да | |
country | Да | |
city | Да | |
phone | Да | |
zip | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Список организаций
Пример запроса
curl -X GET https://api-em.prontosms.ru/v1/email/organizations \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'
Данный метод поддерживает постраничную выдачу результатов.
Пример ответа в случае успеха
{ "total_count":1, "total_pages":1, "page_number":1, "page_size":25, "collection":[ { "id":1, "name":"My Organization", "address":"Lenina 40", "country":"Russia", "city":"Tomsk", "phone":"+7-3822-123-456", "zip":"634000", "current":true } ] }
GET /email/organizations
Ответ сервера
Ответ сервера содержит коллекцию организаций. Каждый элемент содержит следующие атрибуты:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Информация об организации
Пример запроса
curl -X GET https://api-em.prontosms.ru/v1/email/organizations/1 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{ "id":1, "name":"My Organization", "address":"Lenina 40", "country":"Russia", "city":"Tomsk", "phone":"+7-3822-123-456", "zip":"634000", "current":true }
GET /email/organizations/:id
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Организация по умолчанию
Пример запроса
curl -X GET https://api-em.prontosms.ru/v1/email/organizations/current \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{ "id":1, "name":"My Organization", "address":"Lenina 40", "country":"Russia", "city":"Tomsk", "phone":"+7-3822-123-456", "zip":"634000", "current":true }
GET /email/organizations/current
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Задать организацию по умолчанию
Пример запроса
curl -X PATCH https://api-em.prontosms.ru/v1/email/organizations/1/current \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{ "id":1, "name":"My Organization", "address":"Lenina 40", "country":"Russia", "city":"Tomsk", "phone":"+7-3822-123-456", "zip":"634000", "current":true }
PATCH /email/organizations/:id/current
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Изменение организации
Пример JSON для запроса
{ "name":"My Organization", "address":"Lenina 40", "country":"Russia", "city":"Tomsk", "phone":"+7-3822-123-456", "zip":"634000" }
Пример запроса
curl -X PATCH https://api-em.prontosms.ru/v1/email/organizations/1 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' \ -d '...JSON...'
Пример ответа в случае успеха
{ "id":1, "name":"My Organization", "address":"Lenina 40", "country":"Russia", "city":"Tomsk", "phone":"+7-3822-123-456", "zip":"634000", "current":true }
PATCH /email/organizations/:id
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
name | ||
address | ||
country | ||
city | ||
phone | ||
zip |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
id | Идентификатор |
name | Название |
address | Адрес |
country | Страна |
city | Город |
phone | Телефон |
zip | Почтовый индекс |
current | Является ли организацией по умолчанию |
Удаление организации
Пример запроса
curl -X DELETE https://api-em.prontosms.ru/v1/email/organizations/1 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'
DELETE /email/organizations/:id
Рассылки
Создание рассылки
Пример JSON для запроса
{ "from_email":"hello@world.com", "subject":"Hello World", "text":"Hello World", "html":"<h1>Hello World</h1>", "lists":[ { "id":"1" } ] }
Пример запроса
curl -X POST https://api-em.prontosms.ru/v1/email/campaigns \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' \ -d '...JSON...'
Пример запроса для создания рассылки с вложениями
curl -X POST https://api-em.prontosms.ru/v1/email/campaigns \ -H 'Authorization: Bearer $API_TOKEN' \ -F from_email=from@example.com \ -F to=to@example.com \ -F subject='Mail with attachments' \ -F html='<h1>Hello world</h1>' \ -F attachments[]=@/path/to/file1 \ -F attachments[]=@/path/to/file2
Пример ответа в случае успеха
{ "id":1, "from_email":"hello@world.com", "from_name":null, "html":"<h1>Hello World</h1>", "text":"Hello World", "state":"draft", "recipients_count":10, "purchase":{ "enable":true, "subscribers":10, "credits":0, "deficit":0 }, "statistics":{ "delivered":1, "bounced":0, "delivering":0, "uniq_open":0, "uniq_click":0, "unsubscription":0, "spam":0 } }
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 | Количество нажатий кнопки "спам" |
Отправка рассылки
Пример запроса
curl -X PATCH https://api-em.prontosms.ru/v1/email/campaigns/1/deliver \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{ "id":1, "from_email":"hello@world.com", "from_name":null, "html":"<h1>Hello World</h1>", "text":"Hello World", "state":"sending", "recipients_count":10, "purchase":{ "enable":true, "subscribers":10, "credits":0, "deficit":0 }, "statistics":{ "delivered":1, "bounced":0, "delivering":0, "uniq_open":0, "uniq_click":0, "unsubscription":0, "spam":0 } }
PATCH /email/campaigns/:id/deliver
Ответ сервера
Ответ сервера содержит 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 | Количество нажатий кнопки "спам" |
Информация о рассылке
Пример запроса
curl -X GET https://api-em.prontosms.ru/v1/email/campaigns/1 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{ "id":1, "from_email":"hello@world.com", "from_name":null, "html":"<h1>Hello World</h1>", "text":"Hello World", "state":"sending", "recipients_count":10, "purchase":{ "enable":true, "subscribers":10, "credits":0, "deficit":0 }, "statistics":{ "delivered":1, "bounced":0, "delivering":0, "uniq_open":0, "uniq_click":0, "unsubscription":0, "spam":0 } }
GET /email/campaigns/: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 | Количество нажатий кнопки "спам" |
Webhooks
Данный механизм позволяют получать POST запросы на указанный URL, когда происходят события, связанные с одиночными сообщениями.
Структура сообщений, отправляемых на указанный URL:
{ "message": { "id": 1 }, "event": { "name": "clicked", "timestamp": 1539062173, "data": { "url": "https://example.com" } } }
Ключ message содержит информацию о сообщении, с которым связано событие. Ключ event содержит информацию о событии. На данный момент ключ data возвращается только для события clicked, и содержит адрес ссылки, по которой кликнули.
Виды событий
Событие | Описание |
---|---|
delivered | Сообщение доставлено |
opened | Сообщение открыто |
clicked | Получатель перешел по ссылке. Ключ event.data содержит URL ссылки |
unsubscribed | Получатель отписался |
complined | Получатель пожаловался на спам |
skipped | Сообщение не было отправлено (возможные причины: получатель ранее отписался или пожаловался на спам) |
soft_bounced | Сообщение не принято почтовым сервером получателя (возможно, будет принято позже) |
hard_bounced | Сообщение не принято почтовым сервером получателя |
Установка webhook
Пример JSON для запроса
{ "url":"https://example.com/some/path" }
Пример запроса
curl -X POST https://api-em.prontosms.ru/v1/email/webhook \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' \ -d '...JSON...'
Пример ответа в случае успеха
{ "url":"https://example.com/some/path" }
POST /email/webhook
Параметры запроса
Параметр | Описание | Обязательный |
---|---|---|
url | URL, на который отправлять данные о событии | Да |
Ответ сервера
Ответ сервера содержит JSON со следующими атрибутами:
Атрибут | Описание |
---|---|
url | URL, на который отправлять данные о событии |
Получение информации о webhook
Пример запроса
curl -X GET https://api-em.prontosms.ru/v1/email/webhook \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'
Пример ответа в случае успеха
{ "url":"https://example.com/some/path" }
GET /email/webhook
Удаление webhook
Пример JSON для запроса
{ "url":"https://example.com/some/path" }
Пример запроса
curl -X DELETE https://api-em.prontosms.ru/v1/email/webhook \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'
DELETE /email/webhook
SMTP
Базовый URL
Адрес: smtp.msndr.net
Порт: 25
Аутентификация
Имя пользователя: email вашего аккаунта
Пароль: API ключ
Пример SMTP сессии
$ telnet smtp.msndr.net 25 Trying 95.213.163.242... Connected to smtp.msndr.net. Escape character is '^]'. 220 smtp.msndr.net ESMTP service ready ehlo sender 250-smtp.msndr.net 250-STARTTLS 250-AUTH PLAIN LOGIN 250-PIPELINING 250 8BITMIME auth plain AHVzZXJAZXhhbXBsZS5vcmcAc29tZS1zdXBlci1wdXBlci1zZWNyZXQta2V5 235 authentication ok mail from: mail@from.com 250 Ok rcpt to: rcpt@to.com 250 Ok rcpt to: rcpt1@to.com 250 Ok data 354 End data with <CR><LF>.<CR><LF> From: Mail From <mail@from.com> Subject: Hello How are you doing? . 250 Message accepted (sent messages <rcpt@to.com:1>,<rcpt1@to.com:2>) quit 221 smtp.msndr.net closing connection Connection closed by foreign host.
В случае отправки сообщений ответ будет содержать строку с информацией об отправленных письмах.
Строка содержит адреса получателей и ID сообщений в формате <email:id>, объединенные запятой (см. пример выше).