E-mail платформа app.prontosms.ru

Общие сведения

Данный документ содержит сведения о программном интерфейсе сервиса 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) - постраничный способ выдачи данных, используемый в некоторых методах Для управления страницами выдачи списка данных в заголовках запроса необходимо передавать параметры:

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

1 2 3 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:

1 2 3 4 5 6 7 8 { "errors": [ { "code": 412, "detail": "Page size is too big. Max value is 100" } ] }

По умолчанию максимальный page_size равняется 100, если в описании конкретного метода не указано другое.

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

Пример ответа со списком данных (Collection)

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 { "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.

Пример ответа с ошибками

1 2 3 4 5 6 7 8 { "errors":[ { "code":400, "detail":"subject is empty" } ] }

Коды ответов

Код

Описание

Код

Описание

2xx

Запрос успешно выполнен

400

Неверные параметры

401

Аутентификация не пройдена

402

Недостаточно средств

404

Ресурс не найден

415

Неподдерживаемый тип данных

422

Ресурс не может быть обработан

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

На данный момент есть ограничение в 5 запросов в секунду на любые запросы, кроме запросов типа GET. В случае превышения ограничения сервер вернет ответ со статусом 429.

Одиночные сообщения

Отправка одиночного email сообщения

Пример JSON для запроса

1 2 3 4 5 6 7 8 9 { "from_email":"alice@example.org", "from_name": "Alice", "to": "bob@example.org", "subject": "Hello", "text": "Hello, Bob!", "html": "<h1>Hello, Bob!</h1>", "payment": "credit" }

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

1 2 3 4 curl -X POST https://api-em.prontosms.ru/v1/email/messages \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' \ -d '...JSON...'

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 { "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 } }

Пример запроса для отправки сообщения с вложениями

1 2 3 4 5 6 7 8 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

 

Должен присутствовать хотя бы один параметр: text или html

html

 

Должен присутствовать хотя бы один параметр: text или html

attachments

Массив с вложениями. Поддерживается только для запросов с типом содержимого multipart/form-data

 

payment

Способ тарификации сообщения. Возможные значения:
subscriber_priority
credit_priority
subscriber
credit
Значение по умолчанию: subscriber_priority

 

Способы тарификации сообщения

Значение

Описание

Значение

Описание

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. Это означает, что вы превысили количество сообщений, разрешенное к отправке, в единицу времени. Результат отправки сообщений влияет на лимит сообщений в единицу времени. Таким образом, если вы отправляете письма только вашим клиентам, только на существующие адреса, не рассылаете спам и тп, то разрешенное количество сообщений в единицу времени для вашего аккаунта будет увеличиваться, и наоборот.

Получение информации о сообщении

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

1 2 3 4 curl -X GET https://api-em.prontosms.ru/v1/email/messages/1 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' \ -d '...JSON...'

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 { "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 для запроса

1 2 3 4 5 6 7 8 { "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
Значение по умолчанию: subscriber_priority

Нет

Способы тарификации сообщения

Значение

Описание

Значение

Описание

subscriber_priority

Тарифицируется "подписчик", если не доступны "подписчики", используется "письмо". Если нет "писем", возвращается ошибка.

credit_priority

Тарифицируется "письмо". Если нет "писем", используется "подписчик". Если нет "подписчиков", возвращается ошибка.

subscriber

Тарифицируется "подписчик". Если нет "подписчиков", возвращается ошибка.

credit

Тарифицируется "письмо". Если нет "писем", возвращается ошибка.

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

1 2 3 4 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 для запроса

1 2 3 { "title":"My Recipients" }

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

1 2 3 4 curl -X POST https://api-em.prontosms.ru/v1/email/lists \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' \ -d '...JSON...'

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

1 2 3 4 { "id":1, "title":"My Recipients" }

POST /email/lists

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

Параметр

Описание

Обязательный

Параметр

Описание

Обязательный

title

Название группы получателей. Должно быть уникальным

Да

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:

Атрибут

Описание

Атрибут

Описание

id

Идентификатор созданной группы

title

Название группы

Получение списка групп

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

1 2 3 curl -X GET https://api-em.prontosms.ru/v1/email/lists \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'

Данный метод поддерживает постраничную выдачу результатов.

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 { "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

Название группы

Получение информации о группе

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

1 2 3 curl -X GET https://api-em.prontosms.ru/v1/email/lists/1 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'

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

1 2 3 4 { "id":1, "title":"My Recipients" }

GET /email/lists/:id

где :id - идентификатор группы для запроса информации

Ответ сервера

Ответ сервера в формате JSON содержит следующие атрибуты:

Атрибут

Описание

Атрибут

Описание

id

Идентификатор группы

title

Название группы

Удаление группы

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

1 2 3 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 для запроса

1 2 3 { "title":"New Title" }

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

1 2 3 4 curl -X PATCH https://api-em.prontosms.ru/v1/email/lists/1 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' -d '...JSON...'

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

1 2 3 4 { "id":1, "title":"New Title" }

PATCH /email/lists/:id

где :id - идентификатор группы для запроса информации

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

Параметр

Описание

Обязательный

Параметр

Описание

Обязательный

title

Название группы получателей. Должно быть уникальным

Да

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:

Атрибут

Описание

Атрибут

Описание

id

Идентификатор созданной группы

title

Название группы

Параметры группы получателей

Создание параметра

Пример JSON для запроса

1 2 3 4 { "title":"Age", "kind": "numeric" }

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

1 2 3 4 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...'

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

1 2 3 4 5 6 { "id":11, "title":"Age", "kind":"numeric", "list_id":15 }

POST /email/lists/:id/parameters

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

Параметр

Описание

Обязательный

Параметр

Описание

Обязательный

title

 

Да

kind

Возможные значения:
string
numeric
date
boolean
geo
Значение по умолчанию: string

 

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:

Атрибут

Описание

Атрибут

Описание

id

Идентификатор

title

Название

kind

Тип

Список параметров

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

1 2 3 curl -X GET https://api-em.prontosms.ru/v1/email/lists/1/parameters \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'

Данный метод поддерживает постраничную выдачу результатов.

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 { "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 для запроса

1 2 3 4 { "title":"Age", "kind": "numeric" }

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

1 2 3 4 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...'

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

1 2 3 4 5 6 { "id":11, "title":"Age", "kind":"numeric", "list_id":15 }

PATCH /email/lists/:list-id/parameters/:id

где :list-id - идентификатор группы, :id - идентификатор параметра

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

Параметр

Описание

Обязательный

Параметр

Описание

Обязательный

title

 

 

kind

Возможные значения:
string
numeric
date
boolean
geo
При изменении типа параметра, соответствующие значения обнулятся

 

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:

Атрибут

Описание

Атрибут

Описание

id

Идентификатор

title

Название

kind

Тип

Удаление параметра

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

1 2 3 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 для запроса

1 2 3 4 5 6 7 8 9 10 11 12 13 14 { "email":"alice@example.org", "unconfirmed": true, "values":[ { "parameter_id":"1", "value":"Alice" }, { "parameter_id":"2", "value":"22" } ] }

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

1 2 3 4 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...'

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 { "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

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

Параметр

Описание

Обязательный

Параметр

Описание

Обязательный

email

 

Да

unconfirmed

Создать неподтвержденного получателя. Необходимо задать любое значение, например, true, t или 1. По умолчанию создается подтвержденный получатель

Нет

values

Массив значений для параметров

 

Элементы массива значений

Параметр

Описание

Обязательный

Параметр

Описание

Обязательный

parameter_id

ID параметра группы получателей

Да

value

 

Да

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:

Атрибут

Описание

Атрибут

Описание

id

Идентификатор

email

Адрес

confirmed

Подтвержден получатель или нет

values

Массив значений

Элементы массива значений

Параметр

Описание

Параметр

Описание

parameter_id

ID параметра группы получателей

kind

Тип параметра

value

Значение

Обновление получателя

Пример JSON для запроса

1 2 3 4 5 6 7 8 9 10 11 12 13 { "email":"alice@example.org", "values":[ { "parameter_id":"1", "value":"Alice" }, { "parameter_id":"2", "destroy":"true" } ] }

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

1 2 3 4 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...'

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

1 2 3 4 5 6 7 8 9 10 11 12 13 { "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

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

Параметр

Описание

Обязательный

Параметр

Описание

Обязательный

email

 

Нет

values

Массив значений для параметров

 

Элементы массива значений

Параметр

Описание

Обязательный

Параметр

Описание

Обязательный

parameter_id

ID параметра группы получателей

Да

value

Не может быть одновременно использован с параметром destroy

Нет

destroy

Используется для удаления значения. Для удаления значения необходимо задать любое значение, например, true, t или 1. Не можеть быть использован одновременно с параметром value

Нет

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:

Атрибут

Описание

Атрибут

Описание

id

Идентификатор

email

Адрес

confirmed

Подтвержден получатель или нет

values

Массив значений

Элементы массива значений

Параметр

Описание

Параметр

Описание

parameter_id

ID параметра группы получателей

kind

Тип параметра

value

Значение

Список получателей

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

1 2 3 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.

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 { "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

Идентификатор

email

Адрес

confirmed

Подтвержден получатель или нет

values

Массив значений

Элементы массива значений

Параметр

Описание

Параметр

Описание

parameter_id

ID параметра группы получателей

kind

Тип параметра

value

Значение

Удаление получателя

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

1 2 3 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.

Нет

Массив получателей

Параметр

Описание

Обязательный

Параметр

Описание

Обязательный

email

 

Да

values

Массив значений для параметров

 

Элементы массива значений

Параметр

Описание

Обязательный

Параметр

Описание

Обязательный

parameter_id

ID параметра группы получателей

Да

value

 

Да

Ответ сервера

Параметр

Описание

Параметр

Описание

id

Идентификатор импорта. В дальнейшем может использоваться для получения информации о ходе импорта

status

Статус импорта

Пример JSON для запроса

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 { "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" } ] } ] }

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

1 2 3 4 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...'

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

1 2 3 4 { "id":7, "status":"queued" }

Поиск получателей

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

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

1 2 3 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'

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 { "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

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

Параметр

Описание

Обязательный

Параметр

Описание

Обязательный

email

Искомый адрес

Да

Ответ сервера

Ответ сервера содержит коллекцию получателей в группе. Каждый элемент содержит следующие атрибуты:

Атрибут

Описание

Атрибут

Описание

email

Адрес получателя

recipients

Массив, содержащий информацию о списках, в которых есть искомый получатель

Организации

Создание организации

Пример JSON для запроса

1 2 3 4 5 6 7 8 { "name":"My Organization", "address":"Lenina 40", "country":"Russia", "city":"Tomsk", "phone":"+7-3822-123-456", "zip":"634000" }

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

1 2 3 4 curl -X POST https://api-em.prontosms.ru/v1/email/organizations \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' \ -d '...JSON...'

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

1 2 3 4 5 6 7 8 9 10 { "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

Является ли организацией по умолчанию

Список организаций

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

1 2 3 curl -X GET https://api-em.prontosms.ru/v1/email/organizations \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'

Данный метод поддерживает постраничную выдачу результатов.

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 { "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

Является ли организацией по умолчанию

Информация об организации

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

1 2 3 curl -X GET https://api-em.prontosms.ru/v1/email/organizations/1 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'

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

1 2 3 4 5 6 7 8 9 10 { "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

Является ли организацией по умолчанию

Организация по умолчанию

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

1 2 3 curl -X GET https://api-em.prontosms.ru/v1/email/organizations/current \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'

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

1 2 3 4 5 6 7 8 9 10 { "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

Является ли организацией по умолчанию

Задать организацию по умолчанию

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

1 2 3 curl -X PATCH https://api-em.prontosms.ru/v1/email/organizations/1/current \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'

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

1 2 3 4 5 6 7 8 9 10 { "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 для запроса

1 2 3 4 5 6 7 8 { "name":"My Organization", "address":"Lenina 40", "country":"Russia", "city":"Tomsk", "phone":"+7-3822-123-456", "zip":"634000" }

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

1 2 3 4 curl -X PATCH https://api-em.prontosms.ru/v1/email/organizations/1 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' \ -d '...JSON...'

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

1 2 3 4 5 6 7 8 9 10 { "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

Является ли организацией по умолчанию

Удаление организации

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

1 2 3 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 для запроса

1 2 3 4 5 6 7 8 9 10 11 { "from_email":"hello@world.com", "subject":"Hello World", "text":"Hello World", "html":"<h1>Hello World</h1>", "lists":[ { "id":"1" } ] }

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

1 2 3 4 curl -X POST https://api-em.prontosms.ru/v1/email/campaigns \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' \ -d '...JSON...'

Пример запроса для создания рассылки с вложениями

1 2 3 4 5 6 7 8 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

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 { "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

 

Должен присутствовать хотя бы один параметр: text или html

html

 

Должен присутствовать хотя бы один параметр: 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

Количество нажатий кнопки "спам"

Отправка рассылки

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

1 2 3 curl -X PATCH https://api-em.prontosms.ru/v1/email/campaigns/1/deliver \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 { "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

Количество нажатий кнопки "спам"

Информация о рассылке

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

1 2 3 curl -X GET https://api-em.prontosms.ru/v1/email/campaigns/1 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 { "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:

1 2 3 4 5 6 7 8 9 10 11 12 { "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 для запроса

1 2 3 { "url":"https://example.com/some/path" }

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

1 2 3 4 curl -X POST https://api-em.prontosms.ru/v1/email/webhook \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN' \ -d '...JSON...'

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

1 2 3 { "url":"https://example.com/some/path" }

POST /email/webhook

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

Параметр

Описание

Обязательный

Параметр

Описание

Обязательный

url

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

Да

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:

Атрибут

Описание

Атрибут

Описание

url

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

Получение информации о webhook

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

1 2 3 curl -X GET https://api-em.prontosms.ru/v1/email/webhook \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $API_TOKEN'

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

1 2 3 { "url":"https://example.com/some/path" }

GET /email/webhook

Удаление webhook

Пример JSON для запроса

1 2 3 { "url":"https://example.com/some/path" }

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

1 2 3 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 сессии

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 $ 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>, объединенные запятой (см. пример выше).