Аутентификация
Каждый запрос к API должен нести ваш API-ключ. Ключ действует от имени аккаунта целиком — обращайтесь с ним как с паролем.
Где взять ключ #
Личный кабинет → Аккаунт → API и интеграции. Ключ выглядит как длинная строка из букв и цифр.
Не встраивайте ключ в клиентский код. API отдаёт заголовок
Access-Control-Allow-Origin: *, поэтому запрос технически
выполнится и из браузера — но ключ окажется виден любому посетителю
страницы. Ходите в API только с сервера.
Заголовок Authorization #
Основной способ — Bearer-токен:
Authorization: Bearer YOUR_API_KEYСхема ApiKey тоже принимается — она эквивалентна:
Authorization: ApiKey YOUR_API_KEYcurl 'https://api.dashamail.com/v2/lists' \
-H 'Authorization: Bearer YOUR_API_KEY'Ключ в строке запроса #
Для совместимости со старым API ключ можно передать параметром
api_key. Способ рабочий, но менее безопасный: URL попадает
в логи веб-серверов и прокси.
curl 'https://api.dashamail.com/v2/lists?api_key=YOUR_API_KEY'
Если заголовок Authorization задан, параметр
api_key игнорируется.
Когда запрос не проходит #
| Ситуация | Ответ | Что делать |
|---|---|---|
| Ключ не передан или неизвестен | 401 |
Проверьте, что заголовок доходит до сервера. На некоторых хостингах Apache вырезает Authorization — тогда используйте ?api_key=. |
| Ключ заблокирован | 401 |
Обратитесь в поддержку — ключ мог быть отозван после утечки. |
| Запрос с неразрешённого IP | 401 |
В аккаунте включён белый список IP. Добавьте адрес сервера в личном кабинете. |
| Аккаунт на бесплатном тарифе | 404, code: 4 |
API по умолчанию недоступен на бесплатном тарифе. Напишите в поддержку, чтобы его включили. |
| Аккаунт на модерации или заблокирован | 404, code: 4 |
Текст ответа поясняет причину. Модерация нового аккаунта обычно занимает до 10 минут. |
Субаккаунты #
У ключа субаккаунта права ограничены настройками, заданными владельцем:
доступ к отдельным адресным базам, к созданию рассылок, к разделу
«Обработка входящих». При нехватке прав API возвращает
401 с code: 2 — «Недостаточно прав доступа».
Ключи с ограниченными правами #
Ключ без ограничений делает всё, что разрешено аккаунту. Ключ с правами
открывает только перечисленное. Права задаются при выпуске ключа в кабинете
(Аккаунт → API-ключи → «Выбрать права») и меняются там же кнопкой «Права»
у любого активного ключа; изменение доходит до API в течение минуты.
Ключ, который приложение получило через OAuth (например, ИИ-ассистент через
MCP-сервер mcp.dashamail.ru), получает права с экрана согласия:
там пользователь может оставить приложению меньше запрошенного.
Права иерархичны: send включает write,
write включает read, поэтому у ключа хранится
один верхний уровень на раздел.
| Право | Что открывает |
|---|---|
account.read / account.write | Баланс, отправители, домены / добавление отправителей и доменов |
lists.read / lists.write | Адресные базы и подписчики / их добавление и изменение |
campaigns.read / campaigns.write / campaigns.send | Просмотр рассылок / черновики / тест, запуск, пауза, переотправка |
templates.read / templates.write | Шаблоны |
automations.read / automations.write / automations.send | Автоматизации / их создание / запуск для адреса |
reports.read | Отчёты |
transactional.read / transactional.send | Журнал и статистика транзакционных писем / отправка |
webhooks.read / webhooks.write | Вебхуки |
router.read / router.write | Обработка входящих |
Запрос вне прав ключа получает 403 с code: 62;
недостающее право — в details.required_scope и в заголовке
WWW-Authenticate: Bearer error="insufficient_scope". В API 1.21
такие ключи не принимаются вовсе.
Ограничение частоты #
На аккаунт действует лимит запросов в минуту. При его превышении API
отвечает 429 с code: 58; текст сообщения
содержит текущее значение лимита. Повторите запрос в следующую минуту
или обратитесь в поддержку за повышением лимита.