Формат запросов и ответов

Как передавать параметры #

API принимает параметры тремя способами и объединяет их в один набор:

1. JSON в теле запроса — основной способ для POST и PUT;
2. форма application/x-www-form-urlencoded — принимается для совместимости;
3. строка запроса — обычный способ для GET.

При отправке JSON указывайте Content-Type: application/json. Кодировка — всегда UTF-8; параметра charset из старого API здесь нет.

Конверт успешного ответа #

Успешный ответ всегда устроен одинаково: служебный блок msg и полезная нагрузка data.

{
  "response": {
    "msg": {
      "err_code": 0,
      "text": "OK",
      "type": "message"
    },
    "data": { ... }
  }
}

Читайте данные из response.data. Поле msg на успешном ответе носит справочный характер: при err_code = 0 и type = "message" запрос выполнен.

Что окажется в data, зависит от эндпоинта: объект, массив объектов, либо просто true — если операция ничего не возвращает, кроме факта успеха.

Конверт ошибки #

При ошибке структура другая — response отсутствует, вместо него приходит error, а HTTP-код перестаёт быть 200.

HTTP/1.1 422 Unprocessable Entity

{
  "error": {
    "code": 3,
    "message": "Заданы не все необходимые параметры"
  }
}

code — код ошибки DashaMail, он точнее HTTP-статуса и не меняется между версиями. Полный список — на странице Коды ошибок.

HTTP-коды #

Пустой результат — это 404 #

$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$body   = json_decode($response, true);

if ($status === 404 && ($body['error']['code'] ?? null) === 4) {
    $items = [];                        // пусто — это нормально
} elseif ($status >= 400) {
    throw new RuntimeException($body['error']['message']);
} else {
    $items = $body['response']['data'];
}

Составные значения #

Часть параметров описывает вложенные структуры: список адресных баз для рассылки, набор дополнительных полей, вложения письма, условия маршрута. Такие параметры передаются строкой с JSON внутри.

{
  "list_id": "[128341, 128342]",
  "subject": "Весенняя распродажа"
}

В описании каждого параметра тип указан как JSON-строка. Там, где это допустимо, принимается и настоящий JSON-массив — но строка работает везде, поэтому она надёжнее.

Типы значений #

Постраничный вывод #

Общего счётчика записей API не возвращает. Признак последней страницы — ответ, в котором элементов меньше запрошенного limit, либо 404 с code: 4.

Дополнительные поля подписчика #

Поля подписчика сверх адреса нумерованы: merge_1, merge_2, … Номер — это позиция поля в адресной базе; структуру полей конкретной базы отдаёт запрос одной базы. В новых базах merge_1 — «Имя», merge_2 — «Фамилия».

Тип поля определяет формат значения:

CORS #

API отвечает Access-Control-Allow-Origin: * и обрабатывает предварительные запросы OPTIONS. Это не приглашение ходить в API из браузера: ключ, попавший в клиентский код, компрометирован. Проксируйте вызовы через свой бэкенд.