Management API

Public API (/v1/emails*) — для отправки и чтения писем по mi_live_… / mi_test_… ключу. Всё остальное — управление ресурсами организации (проекты, ключи, домены, шаблоны, вебхуки, список подавления, статистика, аудит) — это Management API.

Management API делает то же самое, что дашборд, и подходит для:

• автоматизации создания доменов и ключей при онбординге клиентов;
• терраформинг-стиля управления конфигурацией (CI поднимает шаблоны, вебхуки, ключи);
• BI-скриптов и внутренних админок поверх ваших организаций;
• self-service: ваш собственный продукт оборачивает MailInfra и создаёт суб-проекты под клиентов.

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

Management API использует сессионный токен пользователя — обычный Authorization: Bearer …, но это не API-ключ проекта.

Authorization: Bearer <session_token>

Получить токен — обменять email/password на пару access + refresh:

POST /v1/auth/login
Content-Type: application/json

{
  "email": "you@company.ru",
  "password": "•••••••••"
}

{
  "data": {
    "access_token": "eyJhbGciOi...",
    "token_type": "bearer",
    "expires_in": 1800
  }
}

access_token живёт 30 минут. Когда он истёк — обменивайте refresh-token (приходит в HttpOnly cookie) через POST /v1/auth/refresh.

Передавайте access_token в заголовке Authorization: Bearer … для всех управляющих эндпоинтов.

Не путайте токены

• mi_live_… / mi_test_… — Public API, отправка и чтение писем.
• <session_token> — Management API, всё остальное.

Передача API-ключа на управляющий endpoint вернёт 401, как и наоборот.

Роли в организации

Каждый пользователь — участник одной или нескольких организаций с одной из ролей:

Роль	Чтение	Создание / изменение ресурсов	Удаление ключевых ресурсов
OWNER	да	да	да (включая саму организацию)
ADMIN	да	да	да (домены, участники)
DEVELOPER	да	да (ключи, шаблоны, вебхуки, suppressions)	нет
VIEWER	да	нет	нет

Если у пользователя меньше прав, чем требует endpoint, ответ — 403 Forbidden. Конкретные требования к роли указаны в каждом разделе.

Структура ресурсов

Organization
├── Member               участник с ролью
├── Domain               верифицируется один раз через DNS
├── Suppression          общий список подавления
├── LegalAcceptance      DPA, Privacy Policy и т.п.
└── Project
    ├── ProjectDomain    привязка верифицированного домена к проекту
    ├── ApiKey           mi_live_…/mi_test_…
    ├── Template         Jinja2-шаблоны
    ├── Webhook          подписки на события доставки
    └── Email            отправленные письма (создаются Public API)

Все управляющие пути имеют префикс /v1/organizations/{organization_id}/..., эндпоинты, относящиеся к проекту — /v1/organizations/{organization_id}/projects/{project_id}/....

Карта эндпоинтов

Ресурс	Endpoint	Гайд
API-ключи	…/projects/{id}/api-keys	API-ключи →
Домены организации	…/domains	Домены →
Привязка доменов к проекту	…/projects/{id}/domains	Домены →
Шаблоны	…/projects/{id}/templates	Шаблоны →
Вебхуки	…/projects/{id}/webhooks	Вебхуки →
Список подавления	…/suppressions	Список подавления →

Ошибки

Формат и коды совпадают с Public API — см. Ошибки и лимиты. Дополнительно к общим:

HTTP	Код	Когда
401	unauthorized	Сессионный токен отсутствует, протух или невалиден
403	forbidden	У пользователя нет нужной роли в организации
404	not_found	Ресурс не найден или не принадлежит этой организации/проекту