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

Данный документ содержит сведения о программном интерфейсе сервиса email рассылок (далее - «API»). Через API внешние приложения получают доступ к системе управлению списками получателей, отправке одиночных email сообщений, рассылок, а также прочий функционал для работы со списками получателей и статистикой рассылок

Базовый URL

Базовый URL для всех запросов

https://api-em.prontosms.ru/v1

Аутентификация

Для удостоверения подлинности запросов, в каждом обращении к API необходимо отправлять заголовок содержащий Ваш ключ.

...

Держите Ваш ключ для доступа к API в секрете.

Формат обмена данных

Для обмена данными используется формат 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'

Поддерживаемые параметры

...

Обработка ответа

Обработка ответа может осуществляться при проверки кода состояния HTTP запроса. Так же в случае неуспешного выполнения запроса, ответ содержит массив данных c описанием ошибок в формате JSON.

...

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

На данный момент есть ограничение в 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 '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

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

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

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

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

...

Обратите внимание на то, что при отправке сообщений сервер может вернуть ответ со статусом 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 со следующими атрибутами:

...

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

В личном кабинете в разделе "Автоматизация", выберите "Одиночное по шаблону" и создайте шаблон письма. Отправляйте письма по этому шаблону с параметрами. Для подстановки параметра в шаблоне используйте конструкцию [%имя параметра%], например [%name%], [%age%] и т.д.

...

где :template_id - идентификатор шаблона

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

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

...

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"
}

...

{
  "id":1,
  "title":"My Recipients"
}

POST /email/lists

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

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

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

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

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

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

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

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

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

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

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

...

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

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

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

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

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

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

...

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

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

В случае успешного удаления сервер вернет пустой ответ со статусом 204.

Редактирование группы

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

{
  "title":"New Title"
}

...

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

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

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

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

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

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

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

{
  "title":"Age",
  "kind": "numeric"
}

...

POST /email/lists/:id/parameters

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

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

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

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

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

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

...

GET /email/lists/:id/parameters

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

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

Изменение параметра

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

{
  "title":"Age",
  "kind": "numeric"
}

...

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

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

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

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

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

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

curl -X DELETE https://api-em.prontosms.ru/v1/email/lists/11/parameters/15 \
     -H 'Content-Type: application/json'                        \
     -H 'Authorization: Bearer $API_TOKEN'

...

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

Получатели

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

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

{
  "email":"alice@example.org",
  "unconfirmed": true,
  "values":[
    {
      "parameter_id":"1",
      "value":"Alice"
    },
    {
      "parameter_id":"2",
      "value":"22"
    }
  ]
}

...

POST /email/lists/:id/recipients

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

...

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

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

...

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

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

{
  "email":"alice@example.org",
  "values":[
    {
      "parameter_id":"1",
      "value":"Alice"
    },
    {
      "parameter_id":"2",
      "destroy":"true"
    }
  ]
}

...

PATCH /email/lists/:list_id/recipients/:id

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

...

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

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

...

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

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

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

...

GET /email/lists/:id/recipients

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

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

...

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

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

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

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

...

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

...

{
  "id":7,
  "status":"queued"
}

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

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

...

GET /email/recipients/search

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

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

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

Организации

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

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

{
  "name":"My Organization",
  "address":"Lenina 40",
  "country":"Russia",
  "city":"Tomsk",
  "phone":"+7-3822-123-456",
  "zip":"634000"
}

...

POST /email/organizations

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

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

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

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

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

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

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

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

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

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

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

...

GET /email/organizations/:id

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

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

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

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

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

...

GET /email/organizations/current

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

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

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

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

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

...

PATCH /email/organizations/:id/current

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

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

Изменение организации

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

{
  "name":"My Organization",
  "address":"Lenina 40",
  "country":"Russia",
  "city":"Tomsk",
  "phone":"+7-3822-123-456",
  "zip":"634000"
}

...

PATCH /email/organizations/:id

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

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

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

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

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

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"
    }
  ]
}

...

{
  "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

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

...

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

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

...

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

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

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

...

PATCH /email/campaigns/:id/deliver

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

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

...

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

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

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

...

Webhooks

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

...

Ключ message содержит информацию о сообщении, с которым связано событие. Ключ event содержит информацию о событии. На данный момент ключ data возвращается только для события clicked, и содержит адрес ссылки, по которой кликнули.

Виды событий

Установка webhook

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

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

...

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

POST /email/webhook

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

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

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

Получение информации о 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 вашего аккаунта

...