Перейти к основному содержимому

MailInfra в ИИ-ассистентах

Если вы пишете интеграцию с помощью ИИ-ассистента, дайте ему нашу документацию — модель перестанет угадывать названия полей и придумывать несуществующие эндпоинты.

Документация опубликована в машиночитаемом виде по стандарту llms.txt:

ФайлЧто внутриКогда использовать
/llms.txtОглавление: ссылки на все страницы с описаниями, базовый URL, схема аутентификацииАссистент умеет ходить в интернет и подтянет нужную страницу сам
/llms-full.txtВся документация одним файлом, ~115 КБАссистент без доступа в интернет — приложите файл к диалогу

Оба файла пересобираются при каждом обновлении документации, поэтому не отстают от сайта.

Быстрый способ​

Вставьте в диалог с ассистентом:

Изучи документацию MailInfra: https://docs.mailinfra.ru/llms-full.txt
Дальше отвечай строго по ней, не выдумывай параметры.

Если ассистент не умеет открывать ссылки — скачайте файл и приложите его:

curl -O https://docs.mailinfra.ru/llms-full.txt

Настройка по клиентам​

Cursor

Настройки → Features → Docs → Add new doc, URL https://docs.mailinfra.ru. После индексации обращайтесь к документации через @Docs в чате.

Чтобы правила действовали на весь проект, положите файл .cursor/rules/mailinfra.md:

Проект отправляет письма через MailInfra (https://docs.mailinfra.ru/llms.txt).
Базовый URL — https://api.mailinfra.ru/v1, аутентификация: Authorization: Bearer mi_live_… .
Всегда передавай заголовок Idempotency-Key в POST /v1/emails.
Ключ бери из переменной окружения MAILINFRA_API_KEY, никогда не вставляй в код.

Claude Code

Добавьте ссылку в CLAUDE.md в корне проекта — файл читается автоматически в начале каждой сессии:

## Отправка писем
Используем MailInfra. Документация: https://docs.mailinfra.ru/llms-full.txt
Ключ — в переменной окружения MAILINFRA_API_KEY.

GitHub Copilot / VS Code

Создайте .github/copilot-instructions.md с тем же содержимым — Copilot подхватывает его как контекст репозитория.

ChatGPT, YandexGPT, GigaChat и прочие чаты

Приложите llms-full.txt к диалогу файлом. Это надёжнее ссылки: не зависит от того, включён ли у модели веб-доступ.

Что стоит сказать ассистенту​

Модели чаще всего ошибаются в четырёх местах. Скопируйте этот блок в контекст — он снимает почти все типовые ошибки в сгенерированном коде:

MailInfra — транзакционный email API.

1. Две разные схемы аутентификации:
   - Отправка и чтение писем (/v1/emails*) — API-ключ проекта:
     Authorization: Bearer mi_live_… (или mi_test_… для sandbox).
   - Всё остальное (домены, ключи, шаблоны, вебхуки, подавления) —
     Management API на сессионном токене пользователя. API-ключ там НЕ работает.

2. Требования к полю "from" зависят от окружения ключа:
   - mi_live_… (LIVE) — адрес обязан быть на верифицированном домене,
     иначе 422 domain_not_verified.
   - mi_test_… (TEST) — любой адрес принимается как есть,
     верифицировать домен не нужно.

3. POST /v1/emails на новый запрос отвечает 202 Accepted. Повтор с тем же
   Idempotency-Key — это 200 OK, заголовок Idempotent-Replayed: true и то же
   тело, что и в первый раз. 200 здесь тоже успех: не пиши клиент, который
   принимает только 202.
   Статус в теле ответа зависит от окружения ключа:
   - LIVE → "QUEUED". Это значит «принято в очередь», а НЕ «доставлено».
     Итоговый статус приходит вебхуком или через GET /v1/emails/{id}.
   - TEST → "SIMULATED". Письмо сохранено, но никому не отправляется.
     Вебхук события simulated при этом приходит, так что интеграцию
     можно проверить end-to-end. TEST не применяет список подавления
     и не расходует месячную квоту.
   Не пиши код, который ждёт "QUEUED" в ответ на запрос с TEST-ключом.

4. Тело письма задаётся либо html/text, либо template + variables.
   Одновременно html и template не передаются.

Всегда передавай Idempotency-Key в POST /v1/emails — при ретрае
без него клиент получит дубль письма.

Безопасность​

Не отдавайте ассистенту боевой ключ

mi_live_… даёт право реальной отправки от имени вашего домена. Агент, запущенный в цикле, способен израсходовать месячную квоту или разослать писем на реальных получателей.

Разумный порядок работы:

  • Для отладки с ассистентом заведите отдельный ключ mi_test_… — тот же эндпоинт и та же схема ответа, но письма только сохраняются со статусом SIMULATED и никому не доставляются.
  • Ключ держите в переменной окружения, а не в тексте диалога: всё, что вы вставили в чат, уходит провайдеру модели.
  • Права ключа режьте под задачу: SENDING_ONLY для сервиса отправки, READ_ONLY для аналитики. Подробности — в API-ключах.
  • Боевой ключ выпускайте, когда интеграция уже работает на mi_test_….

Индексация ИИ-краулерами​

Документация открыта для индексации целиком, включая краулеры OpenAI, Anthropic, Perplexity, Google и Яндекса — см. robots.txt. Отдельная регистрация или плагин для этого не нужны: ассистент с веб-доступом найдёт страницы сам.