# Mailganer API

> REST API сервиса email-рассылок Mailganer: подписчики, списки, сегменты, переменные, теги, рассылки, триггеры, товарные рекомендации, пользователи, шаблоны, отчёты, постбек и вебхуки.

- Базовый адрес: `https://mailganer.com`, формат JSON.
- Авторизация: ключ в заголовке `Authorization: CodeRequest <api_key>`. Исключения: методы `/api/v1/` принимают ключ в теле запроса в поле `api_key`, у постбека свои правила (раздел "Постбек").
- Ключ API: личный кабинет, раздел https://mailganer.com/app/profile/settings/api/
- Лимит: 500 запросов в минуту, при превышении ответ 429.
- Некоторые методы отдают данные страницами по 25 записей: поля `count`, `next`, `previous`, `results`.
- Отправка писем по SMTP описана отдельно, со своей авторизацией: https://documentation.samotpravil.ru/
- Python: официальная библиотека `pip install mailganer`.

## Документация

- [Вся документация одним файлом](https://documentation.mailganer.com/llms-full.txt): гайды и все методы с параметрами, примерами curl и ответов
- [OpenAPI-спецификация](https://documentation.mailganer.com/openapi.yaml): машиночитаемое описание всех методов, OpenAPI 3.0

## Гайды

- [Mailganer API](https://documentation.mailganer.com/guides/): REST API Mailganer позволяет управлять подписчиками, списками, сегментами, рассылками, триггерами, отчётами и другими сущностями программно.
- [Библиотеки](https://documentation.mailganer.com/guides/libraries/): Официальные клиенты REST API Mailganer. Библиотека сама подставляет ключ API, повторяет запрос при превышении лимита, обходит страницы и превращает ошибки API в понятные исключения.
- [Библиотека для Python](https://documentation.mailganer.com/guides/libraries/python/): Официальная библиотека для Python: mailganer на PyPI. Она подставляет ключ API, повторяет запрос при превышении лимита, обходит страницы и превращает ошибки API в понятные исключения. Python 3.8 и новее, без внешних зависимостей, лицензия MIT.
- [Авторизация](https://documentation.mailganer.com/guides/authentication/): В API сосуществуют две версии методов с разной авторизацией.
- [Лимиты и пагинация](https://documentation.mailganer.com/guides/rate-limits/): Не чаще **500 запросов в минуту**. При превышении API возвращает `429 Too Many Requests`.
- [Документация для ИИ](https://documentation.mailganer.com/guides/ai-assistants/): Интеграцию с Mailganer можно поручить Cursor, Claude, ChatGPT или другому ассистенту. Чтобы он писал рабочий код, а не угадывал адреса и поля, дайте ему документацию в удобном для него виде.
- [Примеры интеграции](https://documentation.mailganer.com/guides/integrations/): Готовые решения типовых задач через API.
- [Сервисное письмо по событию](https://documentation.mailganer.com/guides/integrations/service-email/): Трек-номер, смена статуса заказа, напоминание об оплате: ваша система делает один запрос, Mailganer сразу отправляет письмо покупателю. Пример ниже для трек-номера, остальные сценарии настраиваются так же.
- [Подписка с сайта или из CRM](https://documentation.mailganer.com/guides/integrations/subscribe-from-site/): Покупатель оставил почту в форме, зарегистрировался или оформил заказ: ваша система передаёт адрес в Mailganer вместе с именем, телефоном и своими полями. Дальше по нему работают рассылки и триггеры.
- [Синхронизация отписок с CRM](https://documentation.mailganer.com/guides/integrations/unsubscribe-sync/): Отписки синхронизируются в обе стороны. Если клиент отказался от рассылок в личном кабинете на вашем сайте, передайте это в Mailganer, и письма ему приходить перестанут. Если он отписался по ссылке в письме или нажал "Это спам", Mailganer сообщит об этом вашей CRM.
- [Статистика в своей аналитике](https://documentation.mailganer.com/guides/integrations/stats-export/): Цифры по рассылкам и триггерам можно забирать к себе в BI, хранилище или таблицу по расписанию, например раз в сутки.

## Методы API

Полное описание методов раздела (параметры, curl, пример ответа) лежит в файле по ссылке у заголовка раздела.

### [Подписчики](https://documentation.mailganer.com/llms/subscribers.txt)

- `GET /api/v2/emails/` Получение информации о подписчиках (по имейлу и фильтрам) (`getSubscribers`)
- `POST /api/v2/emails/` Добавление подписчика (одного или массово) (`createSubscriber`)
- `GET /api/v2/emails/{email_hash}/` Получение информации о подписчике по mg_hash (`getSubscriberByHash`)
- `PATCH /api/v2/emails/{email_hash}/` Обновление информации о подписчике по mg_hash (`updateSubscriberByHash`)
- `PATCH /api/v2/emails/update/` Обновление информации о подписчике по имейлу (`updateSubscriber`)
- `POST /api/v2/emails/{email_hash}/unsubscribe/` Отписка подписчика по mg_hash (`unsubscribeSubscriberByHash`)
- `POST /api/v2/emails/unsubscribe/` Отписка подписчика по имейлу (`unsubscribeSubscriber`)
- `POST /api/v2/emails/validate/` Валидация подписчика (`validateSubscriber`)
- `PATCH /api/v2/emails/mass/` Массовое обновление подписчиков (`updateSubscribersBulk`)
- `POST /api/v3/emails/` Массовое добавление подписчиков (v3) (`createSubscribersV3`)

### [Списки](https://documentation.mailganer.com/llms/lists.txt)

- `GET /api/v2/sites/` Получить массив списков (`listLists`)
- `POST /api/v2/sites/` Создать список (`createList`)
- `GET /api/v2/sites/verify_domain/` Проверка верификации домена (`verifyListDomain`)
- `POST /api/v2/sites/set_webhook` Задать ссылку на webhook (`setListWebhook`)

### [Сегменты](https://documentation.mailganer.com/llms/segments.txt)

- `GET /api/v2/segments/` Получить массив сегментов (`listSegments`)
- `POST /api/v2/segments/` Создать сегмент (`createSegment`)
- `GET /api/v2/segments/{segment_id}` Получить информацию о сегменте (`getSegment`)
- `POST /api/v2/segments/{segment_id}/send_trigger/` Отправка триггера на сегмент (`sendSegmentTrigger`)

### [Переменные](https://documentation.mailganer.com/llms/variables.txt)

- `GET /api/v2/user_vars/` Получить список пользовательских переменных (`listUserVars`)
- `POST /api/v2/user_vars/` Добавление пользовательской переменной (`createUserVar`)

### [Теги](https://documentation.mailganer.com/llms/tags.txt)

- `GET /api/v2/tags/` Получить список тегов (`listTags`)
- `POST /api/v2/tags/` Добавление тега (`createTag`)

### [Рассылки](https://documentation.mailganer.com/llms/mailings.txt)

- `POST /api/v1/mailing/create/` Создание рассылки (`createMailing`)
- `POST /api/v2/mailing/send/` Отправка рассылки (`sendMailing`)
- `GET /api/v2/mailing/{public_id}` Получение информации о рассылке (`getMailing`)
- `GET /api/v2/mailing/` Получить список рассылок (`listMailings`)
- `GET /api/v2/mailing/{public_id}/stat/` Статистика по рассылке (`getMailingStats`)

### [Триггеры](https://documentation.mailganer.com/llms/triggers.txt)

- `POST /api/v2/triggers/{trigger_id}/send/` Отправка триггера (`sendTrigger`)
- `GET /api/v2/triggers/{trigger_id}/stat/` Статистика триггера (`getTriggerStats`)
- `POST /api/v1/trigger/id_stat/` Получение статистики по отправке триггера (`getTriggerSendStats`)
- `GET /api/v2/triggers/` Получить список триггеров (`listTriggers`)
- `GET /api/v2/triggers/{trigger_id}/meta/` Получить информацию о триггере (`getTriggerMeta`)
- `POST /api/v2/triggers/create/` Создание триггера (`createTrigger`)
- `GET /api/v2/triggers/{trigger_id}/emails/` История имейлов по триггеру (`listTriggerEmails`)

### [Товарные рекомендации](https://documentation.mailganer.com/llms/recommendations.txt)

- `POST /api/v1/recomend/orders/` Передача оформленных заказов (`createRecommendationOrders`)
- `GET /documentation/recomend-layout-guide` Триггеры с товарными рекомендациями (статья, не HTTP-метод) (`getRecommendationLayoutGuide`)
- `POST /api/v2/recomend/orders/` Передача RFM-сегмента (`createRecommendationRfmSegment`)

### [Пользователи](https://documentation.mailganer.com/llms/users.txt)

- `GET /api/v2/users/` Получить список пользователей (`listUsers`)
- `POST /api/v2/users/` Создать пользователя (`createUser`)
- `POST /api/v2/pay/` Получить ссылку на пополнение баланса (`createPaymentLink`)
- `GET /api/v2/users/{id}/` Получить информацию о пользователе (`getUser`)
- `PATCH /api/v2/users/{id}/` Изменить пользователя (`updateUser`)
- `POST /api/auth/` Получение токена другого пользователя (`getUserToken`)
- `GET /api/v2/users/get_balance/` Получить баланс (`getUserBalance`)

### [Шаблоны](https://documentation.mailganer.com/llms/templates.txt)

- `POST /api/v2/template/` Создание шаблона (`createTemplate`)
- `GET /api/v2/template/{template_id}/` Получение HTML-вёрстки шаблона (`getTemplate`)

### [Отчёты](https://documentation.mailganer.com/llms/reports.txt)

- `POST /api/v2/tasks/emails_report` Создать задачу на формирование отчёта (`createReportTask`)
- `GET /api/v2/tasks/{task_id}` Получение статуса задачи (`getReportTask`)
- `GET /api/v2/tasks/{task_id}/download_file` Скачивание готового файла (`downloadReportFile`)

### [Постбек](https://documentation.mailganer.com/llms/postback.txt)

- `GET https://postback.mailganer.com/v1/` Передача конверсий и обновление переменной по ссылке (`getPostbackConversion`)

### Вебхуки (входящие)

Mailganer сам отправляет POST на ваш URL, адрес задаётся методом `setListWebhook`.

- Изменение статуса подписчика (`subscriberStatusChangedWebhook`)
- Изменение данных о подписчике (`subscriberDataChangedWebhook`)
- Взаимодействие с письмом (`mailInteractionWebhook`)
- Срабатывание события в триггере (`triggerEventWebhook`)

## Optional

- [Changelog](https://documentation.mailganer.com/changelog/): изменения API
- [Postman-коллекция](https://documentation.mailganer.com/postman/): все методы для импорта в Postman