• Created by Unknown User (igor.kozlitin@prontosms.ru) on Feb 14, 2023

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

Данный документ содержит сведения о программном интерфейсе сервиса 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

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

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

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

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
Значение по умолчанию: subscriber_priority

Нет

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

Значение

Описание

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

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

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

Ответ сервера содержит 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

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

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

Ответ сервера содержит 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

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

Параметр

Описание

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

email

Да

unconfirmed

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

Нет

values

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

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

Параметр

Описание

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

parameter_id

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

Да

value

Да

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

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

Атрибут

Описание

id

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

email

Адрес

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

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

Параметр

Описание

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

email

Нет

values

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

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

Параметр

Описание

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

parameter_id

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

Да

value

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

Нет

destroy

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

Нет

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

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

Атрибут

Описание

id

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

email

Адрес

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

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

email

Адрес

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.

Нет

tags

Массив значений тегов

Нет

callback_url

url, на который будет отправлен запрос после завершения импорта

нет

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

Параметр

Описание

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

email

Email получателя

Да

values

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

Нет

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

Параметр

Описание

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

parameter_id

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

Да

value

Значение параметра

Да

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

Параметр

Описание

id

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

status

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

callback_url

url, на который будет отправлен запрос после окончании импорта

Пример 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"
        }
      ]
    }
  ],
  "tags":[
    "buyer",
    "regular customer"
  ]
}

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

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",
  "callback_url": null
}

Пример запроса после окончания импорта, если указан callback url

{
  "id":7,
  "status":"completed",
  "callback_url":"https://my-callback-url.com/some-secret"
}

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

Данный метод позволяет осуществить поиск получателя по 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

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

Параметр

Описание

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

email

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

Да

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

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

Атрибут

Описание

email

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

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

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

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

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

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

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>, объединенные запятой (см. пример выше).

  • No labels