API управления аккаунтом

Быстрый старт

Создайте токен в кабинете: Настройки аккаунта → API-токены. Выберите готовый набор прав, нужные ресурсы и срок действия. Секрет показывается один раз. Сохраните его в хранилище секретов вашей интеграции.

# MAILCORE_MANAGEMENT_TOKEN is supplied by your secret store.
curl --fail-with-body https://mailcore.uz/api/management/v1/token/verify \
  --header "Authorization: Bearer $MAILCORE_MANAGEMENT_TOKEN" \
  --header 'Accept: application/json'

curl --fail-with-body https://mailcore.uz/api/management/v1 \
  --header "Authorization: Bearer $MAILCORE_MANAGEMENT_TOKEN"

Ключ управления начинается с mcm_. Ключи отправки mck_ работают с отдельным Email API. Чтобы отправлять письма, создайте ключ отправки для нужного проекта и потока с правом email_keys.write.

Для ИИ-агента укажите ссылку на OpenAPI и имя переменной окружения MAILCORE_MANAGEMENT_TOKEN. Агент сначала проверяет токен и доступные ресурсы, затем выполняет согласованные с вами изменения. Сам ключ в текст задания вставлять не нужно.

Доступ и ресурсы

• Аккаунт: все организации и ресурсы, к которым у создателя токена есть действующий доступ.
• Организации: только выбранные организации и разрешённые действия внутри них.
• Домены: только выбранные домены, их почта и связанные проекты Email API.
• Проекты: только выбранные проекты Email API с публичными ID eaw_….

Права ключа всегда ограничены текущими правами его создателя. Удаление из организации, понижение роли, отзыв или истечение токена прекращают соответствующий доступ. Доступ к оплате, команде, ключам отправки и вебхукам задаётся отдельно. Ключ домена или проекта не даёт доступ к финансам всей организации.

Права на действия

Чтение позволяет получать ресурсы и списки. Изменение включает чтение и доступные операции создания и обновления. Для каждой команды справочник указывает отдельное обязательное право; наличие доступа к домену само по себе не даёт доступ к почтовым ящикам или ключам отправки.

account · organizations · team · domains · mailboxes · aliases
email_projects · email_activity · email_keys · webhooks · billing · audit

<group>.read / <group>.write

Журнал действий доступен только для чтения: audit.read. Изменять или удалять его через ключ нельзя.

Подключение домена и почты

• Создайте или выберите организацию и добавьте домен. Ответ содержит идентификаторы домена и подключения.
• Получите подключение по явным ID организации, домена и заказа. Добавьте выданную TXT-запись у своего DNS-провайдера и запустите проверку владения.
• Выберите тариф и параметры хранения, получите ссылку на оплату и проверьте статус платежа. Для финансовых действий нужно billing.write.
• Запустите создание почты. Проверяйте состояние операции и подключения, затем добавьте требуемые MX/SPF/DKIM/DMARC-записи и запустите финальную проверку.

API возвращает необходимые DNS-записи и проверяет их. Сами записи меняются у DNS-провайдера. Авторизация банковской карты и банковский код подтверждения выполняются на защищённой странице оплаты; API возвращает требуемое действие и ссылку.

Проекты Email API

Создайте проект на подтверждённом домене организации. Маркетинговый поток включается отдельно. Настройте DNS, запустите проверку, создайте ключ отправки и вебхук. История писем, пакетных отправок и очередь доступны с правом email_activity.read отдельно для потоков transactional и marketing.

Пакеты, их стоимость и остаток отправок: GET /organizations/{organization_id}/email-api/billing с правом billing.read. Этот метод возвращает только финансовые сведения. Покупка пакета требует billing.write.

Повторные запросы и фоновые задачи

Каждый POST требует Idempotency-Key. Для новой намеренной операции используйте новое значение; при сетевом сбое повторяйте тот же запрос с прежним значением. Другие данные с тем же ключом вызывают конфликт. Перед повтором создания секрета проверьте результат: потерянный секрет нельзя запросить повторно.

Изменения почты и ресурсов выполняются через ограниченную очередь. Успех HTTP-запроса может означать постановку задачи, а не её завершение. Проверяйте возвращённый статус операции. Перед исполнением ещё не начатой задачи сервер повторно проверяет токен и права создателя; отзыв токена не отменяет уже завершённое изменение.

Соблюдайте Retry-After, повторяйте временные ошибки с увеличивающейся задержкой и не запускайте частый опрос из нескольких параллельных циклов. По умолчанию доступно до 120 запросов в минуту на токен и 600 на аккаунт. Отправка писем имеет собственные лимиты и очередь.

Состояние конкретной операции с ящиком или псевдонимом: GET /organizations/{organization_id}/domains/{domain_id}/operations/{operation_id}. Промежуточные состояния — queued, leased, retry; завершение — done, ошибка — dead. Повторяйте операцию только если ответ разрешает canRetry; для сброса пароля может потребоваться новый пароль.

Ошибки и журнал

Ответы содержат requestId; заголовок X-Request-Id помогает найти обращение в поддержке. 401 — ключ недействителен; 403 — действие или ресурс не разрешены; 409 — конфликт состояния или версии; 422 — неверные поля; 429 — лимит запросов. Временную недоступность зависимости API сообщает отдельно. Перед изменением проверяйте актуальную версию ресурса.

Журнал действий организации доступен с правом audit.read. Для обращения в поддержку достаточно ID запроса, кода ошибки и времени. Не передавайте токен, пароли, банковские коды или тело запроса с секретами.

Справочник методов

Базовый адрес: https://mailcore.uz/api/management/v1. Все ресурсы адресуются явно; API не переключает выбранную организацию в браузере. В таблице приведены действующие методы и требуемые права. Поля запросов и перечисления доступны в OpenAPI.