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

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

Базовый URL

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

https://app.smsgold.ru/v1

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

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

Authorization: Bearer $API_TOKEN

Ключ для доступа к API можно получить в личном кабинете в разделе Автоматизация => API и SMTP => Параметры подключения API и SMTP

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

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

Для обмена данными используется формат JSON, поэтому, в каждом запросе должен присутствовать заголовок

Content-Type: application/json

Все данные от сервера возвращаются так же, в формате JSON.

Получение списков данных (Collection)

Списки данных (Collection) - постраничный способ выдачи данных, используемый в некоторых методах. Для управления страницами выдачи списка данных в заголовках запроса необходимо передавать параметры page_number и page_size:

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

curl -X GET https://app.smsgold.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":8,
    "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	Ресурс не может быть обработан
500	Неизвестная ошибка