# Mailganer API: полная документация > REST API сервиса email-рассылок Mailganer: подписчики, списки, сегменты, переменные, теги, рассылки, триггеры, товарные рекомендации, пользователи, шаблоны, отчёты, постбек и вебхуки. Файл собран автоматически из https://documentation.mailganer.com/openapi.yaml и гайдов https://documentation.mailganer.com/guides/ - Базовый адрес: `https://mailganer.com`, формат JSON. - Авторизация: ключ в заголовке `Authorization: CodeRequest `. Исключения: методы `/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`. ## Общие сведения Методы поделены на несколько групп: 1\. Работа с личным кабинетом Mailganer. Стандартные методы по работе с подписчикам, списками, рассылками. 2\. Интеграция Mailganer со сторонними приложениями. Группа методов называется "Работа с пользователями" Напишите нам на [api@mailganer.com](mailto:api@mailganer.com), если вам не хватает какого то метода. Методы по работе с [SMTP](https://documentation.samotpravil.ru/) задокументированы отдельно и имеют свою отдельную авторизацию ### Авторизация 1\. В методах, содержащих в **url v1,** авторизация происходит через использование апи ключа в теле запроса в переменной _api_key_. 2\. В методах, содержащих в **url v2**, авторизация происходит через использование апи ключа в заголовке `Authorization: CodeRequest {{api_key}}` API ключ находится в разделе [Ключ API](https://mailganer.com/app/profile/settings/api/) личного кабинета ### Лимиты К API можно обращаться не чаще **500 раз в минуту**. В случае превышения лимита, вы получите ошибку с кодом 429. Напишите нам, если требуется увеличить лимит. ### Пагинация Некоторые методы отдают по 25 записей на странице. В переменной count находится количество записей. Ответ находится в json-масиве result. В переменных next и previous находятся ссылки на следующую или предыдущую страницы. Если следующей или предыдущей страницы нет, то вернётся значение null. ``` json { "count": 2, "next": null, "previous": null, "results": [ { "source": 1, "title": "user_var_float", "type": 2, "type_text": "Вещественное число" }, { "source": 1, "title": "user_var_datetime", "type": 4, "type_text": "Дата и время" } ] } ``` ## Гайды ### Mailganer API Адрес: https://documentation.mailganer.com/guides/ REST API Mailganer позволяет управлять подписчиками, списками, сегментами, рассылками, триггерами, отчётами и другими сущностями программно. - **Базовый адрес:** `https://mailganer.com` - **Формат:** JSON - **Полный справочник методов:** [Методы API](https://documentation.mailganer.com/reference/) — с примерами и схемами. - **Интерактивно попробовать:** [Try it (Swagger)](https://documentation.mailganer.com/swagger/) — отправка запросов прямо из браузера. - **Postman:** [коллекция и инструкция по импорту](https://documentation.mailganer.com/postman/) — импортируется в Postman/Insomnia. - **Python:** официальная [библиотека](https://documentation.mailganer.com/guides/libraries/python/), ставится командой `pip install mailganer`. - **Документация для ИИ:** [llms.txt и llms-full.txt](https://documentation.mailganer.com/guides/ai-assistants/) для Cursor, Claude и ChatGPT. - **SMTP:** отправка писем по SMTP описана отдельно, со своей авторизацией — [документация SMTP](https://documentation.samotpravil.ru/). - **Старая документация:** [old-documentation.mailganer.ru](https://old-documentation.mailganer.ru/documentation/api/) — поддерживаем до конца 2026 года. #### Быстрый старт 1. Скопируйте API-ключ в личном кабинете, раздел [Ключ API](https://mailganer.com/app/profile/settings/api/). 2. Все v2-методы принимают ключ в заголовке — см. [Авторизация](https://documentation.mailganer.com/guides/authentication/). 3. Добавьте первого подписчика: **cURL:** ```bash curl --location --request POST 'https://mailganer.com/api/v2/emails/' \ --header 'Authorization: CodeRequest ВАШ_API_КЛЮЧ' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "test@example.com", "source": 49767 }' ``` **Python:** ```bash pip install mailganer ``` ```python from mailganer import Mailganer mg = Mailganer(api_key="ВАШ_API_КЛЮЧ") mg.subscribers.add("test@example.com", source=49767) ``` Подробнее: [Библиотека для Python](https://documentation.mailganer.com/guides/libraries/python/). **Как устроена эта документация** Справочник методов генерируется автоматически из файла `openapi.yaml` — единого источника правды. Гайды (эта и соседние страницы) пишутся вручную в markdown. ### Библиотеки Адрес: https://documentation.mailganer.com/guides/libraries/ Официальные клиенты REST API Mailganer. Библиотека сама подставляет ключ API, повторяет запрос при превышении лимита, обходит страницы и превращает ошибки API в понятные исключения. - [**Python**](https://documentation.mailganer.com/guides/libraries/python/)\ `pip install mailganer`, Python 3.8 и новее, без внешних зависимостей. Для других языков используйте REST API напрямую: примеры есть в [справочнике методов](https://documentation.mailganer.com/reference/) и [Postman-коллекции](https://documentation.mailganer.com/postman/). Код под ваш стек может написать ИИ-ассистент: [как дать ему документацию](https://documentation.mailganer.com/guides/ai-assistants/). ### Библиотека для Python Адрес: https://documentation.mailganer.com/guides/libraries/python/ Официальная библиотека для Python: [mailganer на PyPI](https://pypi.org/project/mailganer/). Она подставляет ключ API, повторяет запрос при превышении лимита, обходит страницы и превращает ошибки API в понятные исключения. Python 3.8 и новее, без внешних зависимостей, лицензия MIT. #### Установка ```bash pip install mailganer ``` #### Ключ API Ключ лежит в личном кабинете, раздел [Ключ API](https://mailganer.com/app/profile/settings/api/). Передайте его в клиент или положите в переменную окружения `MAILGANER_API_KEY`. Вставляйте только сам ключ: заголовок `Authorization: CodeRequest` библиотека соберёт сама, а в v1-методах подставит ключ в тело запроса. ```python from mailganer import Mailganer mg = Mailganer(api_key="ВАШ_API_КЛЮЧ") # или Mailganer() с MAILGANER_API_KEY print(mg.users.balance()) ``` #### Подписчики ```python # добавить одного mg.subscribers.add("user@example.com", source=49767, name="Иван", user_vars={"city": "Москва"}) # до 50 за запрос; записи с ошибкой вернутся в "failed" с причиной mg.subscribers.add_many([ {"email": "a@example.com", "source": 49767, "name": "Аня"}, {"email": "b@example.com", "source": 49767, "name": "Боря"}, ]) # найти, обновить, отписать page = mg.subscribers.list(email="user@example.com") # одна страница, 25 записей for sub in mg.subscribers.list_all(source=49767): # все страницы подряд print(sub["email"]) mg.subscribers.update_by_email("user@example.com", 49767, city="Казань") mg.subscribers.unsubscribe_by_email("user@example.com", 49767) ``` Свои поля в `user_vars` сохраняются, только если переменная заведена в списке. Иначе API примет запрос, но значение не запишет. Завести переменную можно в личном кабинете или методом `mg.variables.create(source, "Трек-номер", mailganer.Variables.STRING, name="track")`. #### Рассылки и триггеры ```python draft = mg.mailings.create(name="Акция", theme="Скидка 20%", segment_id=123456, from_email="news@example.com", from_name="Магазин", html_content="...") mg.mailings.send(draft["public_id"], datetime_send="01.10.2026 10:00") mg.triggers.send(113292, "user@example.com", variables={"order_id": 555}) mg.segments.send_trigger(245611, trigger_id=145674) ``` #### Отчёты ```python task = mg.reports.create("csv", site_id=49767) mg.reports.wait(task["id"]) # ждёт, пока отчёт соберётся open("list.csv", "wb").write(mg.reports.download(task["id"])) ``` #### Вебхуки Адрес для событий задаётся методом `mg.lists.set_webhook(list_id, url)`. Входящий запрос разбирает `parse_webhook`: ```python from mailganer import parse_webhook event = parse_webhook(request_body) if event["event"] == "mail_interaction" and event["action_name"] == "clicked": ... ``` #### Ошибки и лимиты `mg.subscribers.add()` бросает `ValidationError`, если API не принял запись, например из-за неверного email. `mg.triggers.send()` бросает `MailganerError`, если письмо не отправлено: триггер выключен, на модерации или подписчик не активен. Все ошибки наследуют `MailganerError`: `AuthenticationError` для 401, `PermissionDeniedError` для 403, `NotFoundError` для 404, `ValidationError` для 400 с подробностями по полям в `.errors`, а также `RateLimitError` и `ServerError`. При ответах 429, 503 и `throttling` библиотека сама ждёт и повторяет запрос, по умолчанию 2 раза. Число повторов задаёт параметр `max_retries`. Про лимиты API: [Лимиты и пагинация](https://documentation.mailganer.com/guides/rate-limits/). ```python from mailganer import ValidationError try: mg.templates.create(name="Письмо", html="") except ValidationError as e: print(e.errors) # {'html': ['Это поле обязательно.']} ``` #### Метода нет в библиотеке Разделы клиента: `subscribers`, `lists`, `segments`, `variables`, `mailings`, `triggers`, `recommendations`, `users`, `tags`, `templates`, `reports`, `postback`. Имена полей совпадают со [справочником методов](https://documentation.mailganer.com/reference/). Если нужного метода нет, отправьте запрос напрямую: ```python mg.request("GET", "/api/v2/tags/") ``` Новые методы API появляются в библиотеке со следующей версией. Что изменилось, смотрите в [истории версий на PyPI](https://pypi.org/project/mailganer/#history). ### Авторизация Адрес: https://documentation.mailganer.com/guides/authentication/ В API сосуществуют две версии методов с разной авторизацией. #### v2 — заголовок (основной способ) Большинство методов (`/api/v2/...`) авторизуются заголовком: ``` Authorization: CodeRequest ВАШ_API_КЛЮЧ ``` API-ключ лежит в личном кабинете, раздел [Ключ API](https://mailganer.com/app/profile/settings/api/). #### v1 — ключ в теле запроса Некоторые методы `/api/v1/...` (например, создание рассылки, часть триггерных) не используют заголовок, а принимают `api_key` **в теле запроса**. Конкретный способ для каждого метода указан в его описании в [Методы API](https://documentation.mailganer.com/reference/). #### SMTP Отправка писем по SMTP и методы SMTP API описаны в отдельной документации и авторизуются своими данными, не ключом REST API: [документация SMTP](https://documentation.samotpravil.ru/). #### Лимиты См. страницу [Лимиты и пагинация](https://documentation.mailganer.com/guides/rate-limits/). ### Лимиты и пагинация Адрес: https://documentation.mailganer.com/guides/rate-limits/ #### Лимит запросов Не чаще **500 запросов в минуту**. При превышении API возвращает `429 Too Many Requests`. Отдельные методы имеют свои ограничения (указаны в их описании), например: - массовое добавление/обновление подписчиков — до **50** записей за запрос, операция атомарна; - отправка триггеров — свой лимит по частоте. #### Пагинация GET-методы, возвращающие списки, отдают данные постранично — по **25** записей: ```json { "count": 1, "next": null, "previous": null, "results": [] } ``` - `count` — всего записей; - `next` / `previous` — ссылки на соседние страницы; - `results` — массив записей текущей страницы. ### Документация для ИИ Адрес: https://documentation.mailganer.com/guides/ai-assistants/ Интеграцию с Mailganer можно поручить Cursor, Claude, ChatGPT или другому ассистенту. Чтобы он писал рабочий код, а не угадывал адреса и поля, дайте ему документацию в удобном для него виде. #### Файлы для ассистента - [llms.txt](https://documentation.mailganer.com/llms.txt): короткая выжимка. Базовый адрес, авторизация, лимиты, гайды и все методы со ссылками на файлы разделов. - Файлы разделов, например [llms/subscribers.txt](https://documentation.mailganer.com/llms/subscribers.txt): все методы одного раздела с параметрами, примерами curl и ответов. Небольшие, ассистент читает их целиком. - [llms-full.txt](https://documentation.mailganer.com/llms-full.txt): вся документация одним файлом. Удобно положить в проект или приложить к чату. - [openapi.yaml](https://documentation.mailganer.com/openapi.yaml): спецификация OpenAPI 3.0, по ней можно сгенерировать клиент на любом языке. Файлы собираются автоматически из той же спецификации, что и [справочник методов](https://documentation.mailganer.com/reference/), поэтому всегда актуальны. #### Как подключить **Cursor, Claude Code, Codex и другие агенты в редакторе или терминале.** Самый надёжный способ: сохранить документацию в проект, тогда агент прочитает её целиком, а не по кусочкам. ```bash curl -o mailganer-api.md https://documentation.mailganer.com/llms-full.txt ``` Дальше сошлитесь на файл в задаче, например `@mailganer-api.md` в Cursor. Если сохранять файл не хочется, дайте агенту ссылку на [llms.txt](https://documentation.mailganer.com/llms.txt): оттуда он сам перейдёт в нужный раздел. **ChatGPT, Claude и другие чаты.** Скачайте [llms-full.txt](https://documentation.mailganer.com/llms-full.txt) и приложите файлом к сообщению. #### Пример запроса ```text Документация API Mailganer лежит в файле mailganer-api.md. Задача: после оформления заказа на сайте отправлять покупателю письмо с трек-номером через триггер Mailganer. Стек: PHP 8, Laravel. Требования: - ключ API бери из переменной окружения MAILGANER_API_KEY; - учитывай лимит 500 запросов в минуту, при ответе 429 повторяй запрос с паузой; - используй только методы из документации, ничего не придумывай. ``` Для Python попросите ассистента использовать [официальную библиотеку](https://documentation.mailganer.com/guides/libraries/python/) `mailganer`: в ней уже есть повторы при лимитах и обход страниц. #### Безопасность ключа - Не вставляйте ключ API в чат с ассистентом и не коммитьте его в репозиторий. Храните ключ в переменной окружения или в хранилище секретов. - По ключу доступны все методы API вашего аккаунта, включая отписку и изменение подписчиков. Если ключ попал в чужие руки, напишите нам на [api@mailganer.com](mailto:api@mailganer.com). - Проверяйте код ассистента перед запуском на боевых данных, особенно массовые изменения и отписки. ### Примеры интеграции Адрес: https://documentation.mailganer.com/guides/integrations/ Готовые решения типовых задач через API. - [**Сервисное письмо по событию**](https://documentation.mailganer.com/guides/integrations/service-email/)\ Трек-номер, смена статуса заказа, напоминание об оплате: письмо уходит покупателю по одному запросу. - [**Подписка с сайта или из CRM**](https://documentation.mailganer.com/guides/integrations/subscribe-from-site/)\ Передать в Mailganer адрес из формы, регистрации или заказа вместе с именем, телефоном и своими полями. - [**Синхронизация отписок с CRM**](https://documentation.mailganer.com/guides/integrations/unsubscribe-sync/)\ Отписка в личном кабинете сайта доходит до Mailganer, а отписка из письма и жалоба на спам доходят до CRM. - [**Статистика в своей аналитике**](https://documentation.mailganer.com/guides/integrations/stats-export/)\ Забирать цифры по рассылкам и триггерам в BI, хранилище или таблицу по расписанию. ### Сервисное письмо по событию Адрес: https://documentation.mailganer.com/guides/integrations/service-email/ Трек-номер, смена статуса заказа, напоминание об оплате: ваша система делает один запрос, Mailganer сразу отправляет письмо покупателю. Пример ниже для трек-номера, остальные сценарии настраиваются так же. #### 1. Триггер в личном кабинете 1. В разделе [Триггеры](https://mailganer.com/app/trigger/) создайте триггер и выберите список. 2. Событие: "Вызов API метода" (группа "События, связанные с API"), время отправки "Сразу". 3. Сверстайте письмо. Данные из запроса подставляются переменными: ```html

Здравствуйте, {{ first_name }}!

Заказ № {{ order_id }} передан в доставку.

Трек-номер: {{ track_number }}

``` 4. Запустите триггер. После модерации он начнёт принимать запросы. ID триггера есть в адресе страницы: `https://mailganer.com/app/trigger/12345/`. #### 2. Запрос из вашей системы Как только у заказа появился трек-номер, отправьте [`POST /api/v2/triggers/{trigger_id}/send/`](https://documentation.mailganer.com/reference/#operation/sendTrigger): ```bash curl --location 'https://mailganer.com/api/v2/triggers/12345/send/' \ --header 'Authorization: CodeRequest ВАШ_API_КЛЮЧ' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "buyer@example.com", "variables": { "first_name": "Анна", "order_id": 10482, "track_number": "80081234567890", "track_url": "https://example.com/track/80081234567890" } }' ``` Ответ при успешной отправке: ```json { "status": 1, "updated_variables": [], "status_text": "Success. Complete on 0.453127 sec.", "result": 191015674 } ``` `result` это ID отправки. Если `status` не равен 1, причина будет в поле `error`, список ошибок есть в [описании метода](https://documentation.mailganer.com/reference/#operation/sendTrigger). Частота: не больше 300 запросов в минуту. #### Если покупатель отписался от рассылок По умолчанию письмо не уйдёт адресу со статусом "Отписался". Для сервисных писем можно включить параметр `ignore_unsubscribed: true`. Параметр `doi_ok: true` добавит покупателя в список активным подписчиком перед отправкой. Оба параметра подключает [поддержка](https://mailganer.com/app/support/). #### Чтобы письма попадали во входящие - Только сервисное содержание: номер заказа, трек-номер, ссылка на отслеживание. Акции и баннеры отправляйте отдельной рассылкой. - Отправитель на вашем домене с настроенными SPF и DKIM. #### SMS Тот же сценарий работает с SMS-триггером: добавьте в запрос `phone`. ### Подписка с сайта или из CRM Адрес: https://documentation.mailganer.com/guides/integrations/subscribe-from-site/ Покупатель оставил почту в форме, зарегистрировался или оформил заказ: ваша система передаёт адрес в Mailganer вместе с именем, телефоном и своими полями. Дальше по нему работают рассылки и триггеры. #### 1. Что понадобится - ID списка, куда добавлять подписчиков. Он есть в [настройках списков](https://mailganer.com/app/settings/). - Свои поля, например дата последней покупки или номер карты лояльности, заводятся как пользовательские переменные: в настройках списка или методом [`POST /api/v2/user_vars/`](https://documentation.mailganer.com/reference/#operation/createUserVar). #### 2. Запрос [`POST /api/v2/emails/`](https://documentation.mailganer.com/reference/#operation/createSubscriber): ```bash curl --location 'https://mailganer.com/api/v2/emails/' \ --header 'Authorization: CodeRequest ВАШ_API_КЛЮЧ' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "buyer@example.com", "source": 49767, "name": "Анна", "phone": "+79123456789", "add_tag": "форма в футере", "user_vars": {"last_order": "05.10.2026"} }' ``` В ответе придут `id` и `mg_hash` подписчика и его статус в `email_status`. Отправляйте запрос со своего сервера. Ключ API нельзя класть в код страницы: по нему доступен весь аккаунт. #### Подтверждение подписки По умолчанию новый адрес получает статус "Запрошено подтверждение" и письмо со ссылкой. Рассылки начнут приходить после клика. Повторно письмо подтверждения можно отправить не раньше чем через час. Если согласие вы уже получили у себя, например галочкой при оформлении заказа, передайте `"not_doi": true`: подписчик сразу станет активным. Параметр подключает [поддержка](https://mailganer.com/app/support/). #### Обновление данных Изменились имя, телефон или переменная: [`PATCH /api/v2/emails/update/`](https://documentation.mailganer.com/reference/#operation/updateSubscriber) с теми же `email` и `source`. Передаются только поля, которые меняются. Значение `null` в `user_vars` удаляет переменную. ```bash curl --location --request PATCH 'https://mailganer.com/api/v2/emails/update/' \ --header 'Authorization: CodeRequest ВАШ_API_КЛЮЧ' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "buyer@example.com", "source": 49767, "user_vars": {"last_order": "12.10.2026"} }' ``` #### Много адресов сразу В тот же `POST /api/v2/emails/` можно передать массив до 50 подписчиков. Если в одном из них ошибка, не добавится ни один, поэтому проверяйте ответ. При ответе `503` повторите запрос чуть позже. Лимит: 500 запросов в минуту. ### Синхронизация отписок с CRM Адрес: https://documentation.mailganer.com/guides/integrations/unsubscribe-sync/ Отписки синхронизируются в обе стороны. Если клиент отказался от рассылок в личном кабинете на вашем сайте, передайте это в Mailganer, и письма ему приходить перестанут. Если он отписался по ссылке в письме или нажал "Это спам", Mailganer сообщит об этом вашей CRM. #### Из вашей системы в Mailganer [`POST /api/v2/emails/unsubscribe/`](https://documentation.mailganer.com/reference/#operation/unsubscribeSubscriber): ```bash curl --location 'https://mailganer.com/api/v2/emails/unsubscribe/' \ --header 'Authorization: CodeRequest ВАШ_API_КЛЮЧ' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "buyer@example.com", "source": "all" }' ``` `"source": "all"` отписывает из всех списков, вместо него можно передать ID списка или массив ID. Ответ `{"email_status": "unsubscribe"}`. Если адреса нет в списке, придёт `404` и `"Не найдено."`. #### Из Mailganer в вашу систему Mailganer отправляет POST на ваш адрес каждый раз, когда у подписчика меняется статус. **1. Подключите вебхук** в настройках списка на вкладке "Интеграции" или методом [`POST /api/v2/sites/set_webhook`](https://documentation.mailganer.com/reference/#operation/setListWebhook): ```bash curl --location 'https://mailganer.com/api/v2/sites/set_webhook' \ --header 'Authorization: CodeRequest ВАШ_API_КЛЮЧ' \ --header 'Content-Type: application/json' \ --data-raw '{ "id": 49767, "url": "https://crm.example.com/mailganer/hook", "is_active": true, "is_use_auth_key": true, "is_enable_retry": true }' ``` Вебхук настраивается на список. Если списков несколько, подключите его на каждом. **2. Обработайте событие.** Тело приходит как `application/x-www-form-urlencoded`: ``` type=1 email=buyer@example.com status=-1 method=unsubscribe source_id=49767 source_name=Покупатели timestamp=2026-10-05 15:26:19.654599 ``` Для синхронизации отписок смотрите на `type=1` и `status`. При отписке приходит ещё `reason`, причина отписки. | `status` | Что произошло | |---|---| | `-1` | Отписался | | `-3` | Пожаловался на спам | | `-2` | Адрес недоступен | Остальные значения и другие типы событий описаны в [методе вебхука](https://documentation.mailganer.com/reference/#operation/setListWebhook). **3. Ответьте `200`.** С `is_enable_retry: true` при ошибке Mailganer повторит отправку через 5 секунд, 1 час и 24 часа. С `is_use_auth_key: true` в заголовке `Authorization` придёт ключ авторизации: по нему проверяйте, что запрос пришёл от Mailganer. ### Статистика в своей аналитике Адрес: https://documentation.mailganer.com/guides/integrations/stats-export/ Цифры по рассылкам и триггерам можно забирать к себе в BI, хранилище или таблицу по расписанию, например раз в сутки. #### Рассылки за период [`GET /api/v2/mailing/`](https://documentation.mailganer.com/reference/#operation/listMailings) отдаёт рассылки со счётчиками: ```bash curl --location 'https://mailganer.com/api/v2/mailing/?start_date=2026-09-01&end_date=2026-09-30' \ --header 'Authorization: CodeRequest ВАШ_API_КЛЮЧ' ``` ```json { "count": 67, "next": "https://mailganer.com/api/v2/mailing/?end_date=2026-09-30&page=2&start_date=2026-09-01", "results": [ { "public_id": 178532701233, "subject": "Осенняя коллекция", "segment_name": "Покупатели", "send": "2026-09-17T13:11:31.979578", "status_str": "Доставлена", "count_sent": 4907, "count_delivery": 4851, "count_open": 1265, "count_click": 147, "count_unsubscribe": 3, "count_spam": 0 } ] } ``` В примере ответ сокращён. На странице 25 рассылок, следующую берите по ссылке из `next`. #### Рассылка по дням [`GET /api/v2/mailing/{public_id}/stat/`](https://documentation.mailganer.com/reference/#operation/getMailingStats) отдаёт события по дням и итог в `summary`: ```bash curl --location 'https://mailganer.com/api/v2/mailing/178532701233/stat/' \ --header 'Authorization: CodeRequest ВАШ_API_КЛЮЧ' ``` Открытия и клики приходят ещё несколько дней после отправки. Забирайте статистику не только за вчера, а за последние 7 дней и перезаписывайте её у себя. #### Триггеры Список триггеров с ID: [`GET /api/v2/triggers/`](https://documentation.mailganer.com/reference/#operation/listTriggers). Статистика по одному триггеру: [`GET /api/v2/triggers/{trigger_id}/stat/`](https://documentation.mailganer.com/reference/#operation/getTriggerStats). ```bash curl --location 'https://mailganer.com/api/v2/triggers/12345/stat/?start_date=2026-09-01&end_date=2026-09-30' \ --header 'Authorization: CodeRequest ВАШ_API_КЛЮЧ' ``` С обеими датами придут цифры по дням и `summary`. Без дат или с одной датой только `summary` за всё время. #### Отчёт по рассылке файлом Общий отчёт или отчёт по кликам в CSV или XLSX. Файл собирается в фоне: 1. [`POST /api/v2/tasks/emails_report`](https://documentation.mailganer.com/reference/#operation/createReportTask) с `mailing_id`, `mailing_report_type` (`general_mailing_report` или `clicks`) и `file_type` (`csv` или `xlsx`). В ответе `task_id`. 2. [`GET /api/v2/tasks/{task_id}`](https://documentation.mailganer.com/reference/#operation/getReportTask), пока `state` не станет `COMPLETED`. 3. [`GET /api/v2/tasks/{task_id}/download_file`](https://documentation.mailganer.com/reference/#operation/downloadReportFile) отдаёт файл. ```bash curl --location 'https://mailganer.com/api/v2/tasks/emails_report' \ --header 'Authorization: CodeRequest ВАШ_API_КЛЮЧ' \ --header 'Content-Type: application/json' \ --data-raw '{ "mailing_id": 178532701233, "mailing_report_type": "general_mailing_report", "file_type": "csv" }' ``` Методы отчётов работают, только если в аккаунте включено ограничение доступа к API по IP-адресам. Без него ответ `403`. ## Методы API ### Подписчики Управление подписчиками (добавление, обновление, отписка, валидация) #### Получение информации о подписчиках (по имейлу и фильтрам) `GET https://mailganer.com/api/v2/emails/` · operationId: `getSubscribers` Возвращает информацию о подписчике(ах) с фильтрацией по query-параметрам. **Эндпоинт:** `GET https://mailganer.com/api/v2/emails/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` ##### Query-параметры | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `email` | string | нет | Имейл, о котором нужна информация; оставьте пустым, чтобы получить по всем подписчикам | | `source` | int | нет | ID списка; оставьте пустым, чтобы получить по всем спискам | | `start_date` | string | нет | Фильтр по дате создания подписчика (формат `YYYY-MM-DD`) | | `end_date` | string | нет | Фильтр по дате создания подписчика (формат `YYYY-MM-DD`) | | `updated_at_start` | string | нет | Фильтр по дате изменения подписчика (формат `YYYY-MM-DD`) | | `updated_at_end` | string | нет | Фильтр по дате изменения подписчика (формат `YYYY-MM-DD`) | | `last_activity_days` | int | нет | Передайте `1`, чтобы дополнительно вернуть в ответе поле активности подписчика | ##### Пример curl ```bash curl --location --request GET 'https://mailganer.com/api/v2/emails/?email=test@example.com&source=51488' \ --header 'Authorization: CodeRequest {{api_key}}' ``` ##### Примечания - При фильтрации по имейлу `count` всегда равен `1`. - Если параметры дат не указаны — возвращаются все подписчики. - Активностью считается последнее открытие рассылки или триггерного письма. - Поле активности рассчитывается только если передан `last_activity_days=1`. - Ответ постраничный: поля `next` / `previous` / `count` / `results`. **Ответы:** `200` Email найден, `400` Ошибка (400) — неверный source Пример ответа `200`: ```json { "count": 1, "next": null, "previous": null, "results": [ { "id": 115986334, "mg_hash": "ae2f6611598633414be10fe73380863cb59afe7b8", "email": "vlad.tochonii@mailganer.ru", "source": 57229, "email_status": "active", "corrected_email": null, "name": "", "patronymic": "", "surname": "", "gender": 0, "birthday": null, "phone": null, "city": "", "country": "", "is_valid": true, "doi_is_delivery": true, "doi_is_open": false, "doi_is_click": false, "user_vars": { "nps": "ok", "test_date": 1667520000 }, "bunce_log": null } ] } ``` #### Добавление подписчика (одного или массово) `POST https://mailganer.com/api/v2/emails/` · operationId: `createSubscriber` Добавляет нового подписчика в указанный список (или списки). **Эндпоинт:** `POST https://mailganer.com/api/v2/emails/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` ##### Обязательные поля | Поле | Тип | Описание | |---|---|---| | `email` | string | Имейл подписчика | | `source` | int / array / `"all"` | ID списка. `"all"` — во все списки; можно передать массив ID | ##### Необязательные поля | Поле | Тип | Описание | |---|---|---| | `phone` | string | Телефон | | `name`, `surname`, `patronymic` | string | ФИО | | `gender` | int | 1 — мужской, 2 — женский | | `birthday` | string | Дата рождения, формат `dd.mm.yyyy` | | `city` | string | Город | | `add_tag` / `delete_tag` | string / array | Добавить / удалить метку (≤ 140 символов) | | `add_category` / `delete_category` | string | Добавить / удалить категорию (≤ 250 символов) | | `user_vars` | object | Пользовательские переменные (`null` в значении — удалить его) | | `not_doi` / `need_activate` | bool | Управление DOI (требует активации поддержкой) | ##### Пример curl ```bash curl --location --request POST 'https://mailganer.com/api/v2/emails/' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "test@example.com", "source": 49767 }' ``` ##### Примечания - Лимит: **500 запросов/мин**, иначе `429`. - Ошибка `400` «We have already sent a subscription confirmation email…» — повторное DOI-письмо доступно через 1 час. - Рекомендуется **v3** ([`/api/v3/emails/`](#operation/createSubscribersV3)) — детальный ответ с массивами `successful` / `failed`. ##### Массовое добавление До 50 подписчиков за один запрос: тело — JSON-массив тех же объектов. На странице «Попробовать» пример выбирается в списке примеров тела. ###### Тело запроса Массив объектов; поля каждого объекта: | Поле | Тип | Обяз. | Описание | | --- | --- | --- | --- | | `email` | string | да | Имейл подписчика | | `source` | int / array / `"all"` | да | ID списка; можно передать несколько или `"all"` — во все списки | | `phone` | string | нет | Телефон | | `name` | string | нет | Имя | | `surname` | string | нет | Фамилия | | `patronymic` | string | нет | Отчество | | `gender` | int | нет | 1 — мужской, 2 — женский | | `birthday` | string | нет | Дата рождения, формат `dd.mm.yyyy` | | `city` | string | нет | Город | | `add_tag` | string / array | нет | Добавить метку (≤ 140 символов) | | `delete_tag` | string | нет | Удалить метку | | `user_vars` | object | нет | Пользовательские переменные | | `not_doi` | bool | нет | Отменить отправку письма подтверждения | | `need_activate` | bool | нет | Отправить письмо подтверждения | | `add_category` | string | нет | Добавить категорию подписки (≤ 250 символов) | | `delete_category` | string | нет | Удалить категорию подписки | ###### Пример curl ```bash curl --location --request POST 'https://mailganer.com/api/v2/emails/' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data-raw '[ {"email": "test1@example.com", "source": 51488, "name": "Федор"}, {"email": "test2@example.com", "source": 51488, "name": "Пётр"} ]' ``` ###### Примечания - Максимум **50** имейлов за запрос. - Атомарность: если хотя бы в одном имейле есть ошибка, **ни один** имейл из пакета не будет добавлен. - В ответе по каждому имейлу возвращаются `id`, `mg_hash`, `in_base` (был ли уже в базе) и `email_status`. - Повторная отправка DOI-письма возможна через 1 час. - При `HTTP 503` необходимо повторить запрос с задержкой. **Ответы:** `201` Success, `400` Error, `401` Error - Недопустимый токен Пример ответа `201`: ```json { "id": 143788300, "mg_hash": "0aa106143788300b392b80ecf023c57d75cc70272", "email": "test@example.com", "source": 60958, "email_status": "fixed", "corrected_email": null, "name": "Федор", "patronymic": "Федорович", "surname": "Федоров", "gender": 1, "birthday": "01.01.1988", "phone": "+79123456789", "city": null, "country": null, "is_valid": false, "doi_is_delivery": false, "doi_is_open": false, "doi_is_click": false, "user_vars": null, "bunce_log": "Global stop list email hash: 554d1a357108862d8de2356531c004a3baf9403" } ``` #### Получение информации о подписчике по mg_hash `GET https://mailganer.com/api/v2/emails/{email_hash}/` · operationId: `getSubscriberByHash` Возвращает информацию о конкретном подписчике по хэшу имейла (`mg_hash`) в URL. **Эндпоинт:** `GET https://mailganer.com/api/v2/emails/:email_hash/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` Подписчик определяется по path-переменной `email_hash` (значение `mg_hash`). Query-параметры не требуются. ##### Пример curl ```bash curl --location --request GET 'https://mailganer.com/api/v2/emails/ae2f6611598633414be10fe73380863cb59afe7b8/' \ --header 'Authorization: CodeRequest {{api_key}}' ``` ##### Примечания - Возвращается тот же формат объекта подписчика, что и в способе 1 (поля `id`, `mg_hash`, `email`, `source`, `email_status`, `user_vars`, `tags`, `categories`, `created`, `modified` и др.). - Если подписчик по хэшу не найден — вернётся ошибка «Не найдено.». **Ответы:** `200` Успех (200) Пример ответа `200`: ```json { "id": 321456817, "mg_hash": "54ede83211718173f544604ebe5ad1867543b348185", "email": "test@gmail.com", "source": 104363, "email_status": "active", "corrected_email": null, "name": "", "patronymic": "", "surname": "", "gender": 0, "birthday": null, "phone": null, "city": null, "country": null, "is_valid": false, "doi_is_delivery": false, "doi_is_open": false, "doi_is_click": false, "user_vars": { "date_glob": null, "glob": 66432 }, "bunce_log": null, "tags": [], "categories": [], "created": "2026-03-03T16:06:29.724362", "modified": "2026-03-03T16:06:29.740263" } ``` #### Обновление информации о подписчике по mg_hash `PATCH https://mailganer.com/api/v2/emails/{email_hash}/` · operationId: `updateSubscriberByHash` Обновляет информацию о подписчике, идентифицируя его по хэшу имейла (`mg_hash`) в URL. **Эндпоинт:** `PATCH https://mailganer.com/api/v2/emails/:email_hash/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` Подписчик определяется по `mg_hash` в пути (path-переменная `email_hash`), поэтому передавать `email` и `source` в теле не требуется — в теле указываются только обновляемые поля. ##### Тело запроса | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `phone` | string | нет | Телефон | | `name` | string | нет | Имя | | `surname` | string | нет | Фамилия | | `patronymic` | string | нет | Отчество | | `gender` | int | нет | 1 — мужской, 2 — женский | | `birthday` | string | нет | Дата рождения, формат `dd.mm.yyyy` | | `city` | string | нет | Город | | `add_tag` | string / array | нет | Добавить метку | | `delete_tag` | string | нет | Удалить метку | | `user_vars` | object | нет | Пользовательские переменные (передайте `null` в значении, чтобы удалить переменную) | | `not_doi` | bool | нет | Отменить отправку письма подтверждения | | `need_activate` | bool | нет | Отправить письмо подтверждения | | `add_category` | string | нет | Добавить категорию подписки | | `delete_category` | string | нет | Удалить категорию подписки | ##### Пример curl ```bash curl --location --request PATCH 'https://mailganer.com/api/v2/emails/a05ad557332370764cd4f267a251f3b13289bcff/' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "birthday": "02.01.1990" }' ``` ##### Примечания - Переменные (`user_vars`) обновляются только если явно переданы в запросе. - Чтобы удалить значение пользовательской переменной, передайте `null` — работает для всех типов переменных. - Альтернативные способы обновления: эндпоинт `/api/v2/emails/update/` (передача `email` + `source` в теле) или массовое обновление `/api/v2/emails/mass/`. **Ответы:** `200` Успех (200), `400` Ошибка (400) Пример ответа `200`: ```json { "id": 45763880, "mg_hash": "53158545763880e054b31ecbad2cf3265d4001d1" } ``` #### Обновление информации о подписчике по имейлу `PATCH https://mailganer.com/api/v2/emails/update/` · operationId: `updateSubscriber` Обновляет информацию о подписчике, идентифицируя его по паре `email` + `source` в теле запроса. **Эндпоинт:** `PATCH https://mailganer.com/api/v2/emails/update/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` ##### Тело запроса | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `email` | string | да | Имейл подписчика | | `source` | int / array / `"all"` | да | ID списка; можно передать несколько `[49767,50145]` или `"all"` | | `phone` | string | нет | Телефон | | `name` | string | нет | Имя | | `surname` | string | нет | Фамилия | | `patronymic` | string | нет | Отчество | | `gender` | int | нет | 1 — мужской, 2 — женский | | `birthday` | string | нет | Дата рождения, формат `dd.mm.yyyy` | | `city` | string | нет | Город | | `add_tag` | string / array | нет | Добавить метку | | `delete_tag` | string | нет | Удалить метку | | `user_vars` | object | нет | Пользовательские переменные (передайте `null` в значении, чтобы удалить переменную) | | `not_doi` | bool | нет | Отменить отправку письма подтверждения | | `need_activate` | bool | нет | Отправить письмо подтверждения | | `add_category` | string | нет | Добавить категорию подписки | | `delete_category` | string | нет | Удалить категорию подписки | ##### Пример curl ```bash curl --location --request PATCH 'https://mailganer.com/api/v2/emails/update/' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "test@example.com", "source": "51488", "birthday": "05.01.1990" }' ``` ##### Примечания - Переменные (`user_vars`) обновляются только если явно переданы в запросе; значение `null` удаляет переменную (для всех типов). - Альтернативные способы: передача `mg_hash` в URL (`/api/v2/emails/:email_hash/`) или массовое обновление `/api/v2/emails/mass/`. **Ответы:** `200` Успех (200), `400` Ошибка (400) Пример ответа `200`: ```json { "id": 45763880, "mg_hash": "53158545763880e054b31ecbad2cf3265d4001d1" } ``` #### Отписка подписчика по mg_hash `POST https://mailganer.com/api/v2/emails/{email_hash}/unsubscribe/` · operationId: `unsubscribeSubscriberByHash` Отписывает подписчика, идентифицируя его по хэшу имейла (`mg_hash`) в URL. Это рабочий способ отписки. **Эндпоинт:** `POST https://mailganer.com/api/v2/emails/:email_hash/unsubscribe/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` Подписчик определяется по path-переменной `email_hash` (значение `mg_hash`). Тело запроса не требуется. ##### Пример curl ```bash curl --location --request POST 'https://mailganer.com/api/v2/emails/a05ad557332370764cd4f267a251f3b13289bcff/unsubscribe/' \ --header 'Authorization: CodeRequest {{api_key}}' ``` ##### Примечания - Успешный ответ: `{"email_status": "unsubscribe"}` — статус подписки меняется на «Отписался». - Если подписчик по хэшу не найден — вернётся ошибка `{"status": "error", "error": "Не найдено."}`. **Ответы:** `200` Успех (200), `404` Ошибка (404) Пример ответа `200`: ```json { "email_status": "unsubscribe" } ``` #### Отписка подписчика по имейлу `POST https://mailganer.com/api/v2/emails/unsubscribe/` · operationId: `unsubscribeSubscriber` Отписывает подписчика, идентифицируя его по паре `email` + `source` в теле запроса. **Эндпоинт:** `POST https://mailganer.com/api/v2/emails/unsubscribe/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` ##### Тело запроса | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `email` | string | да | Имейл подписчика | | `source` | int / array / `"all"` | да | ID списка; можно передать несколько или `"all"` | ##### Пример curl ```bash curl --location --request POST 'https://mailganer.com/api/v2/emails/unsubscribe/' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "test@example.com", "source": "51488" }' ``` ##### Примечания - Успешный ответ: `{"email_status": "unsubscribe"}` — статус подписки меняется на «Отписался». - Если подписчик не найден — вернётся ошибка `{"status": "error", "error": "Не найдено."}`. **Ответы:** `200` Успех (200), `404` Ошибка (404) Пример ответа `200`: ```json { "email_status": "unsubscribe" } ``` #### Валидация подписчика `POST https://mailganer.com/api/v2/emails/validate/` · operationId: `validateSubscriber` Проверяет валидность имейла. Валидация тарифицируется отдельно. **Эндпоинт:** `POST https://mailganer.com/api/v2/emails/validate/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` ##### Тело запроса | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `email` | string | ✔ | Имейл | | `source` | int | ✔ | ID списка | ##### Пример curl ```bash curl --location --request POST 'https://mailganer.com/api/v2/emails/validate/' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "test@example.com", "source": 49767 }' ``` ##### Примечания - При слишком частых запросах по одному имейлу — ошибка «Email to many add method». - В ответе `is_valid` показывает результат проверки; `corrected_email` — исправленный имейл (если было исправление). **Ответы:** `200` Успех (200) Пример ответа `200`: ```json { "id": 305384342, "mg_hash": "b9827434aeaa159e4c3a723a4a3e91d", "email": "test@internet.ru", "source": 93455916, "email_status": "wait_activated", "corrected_email": "test@internet.ru", "name": "", "patronymic": "", "surname": "", "gender": 0, "birthday": null, "phone": null, "city": null, "country": null, "is_valid": true, "doi_is_delivery": false, "doi_is_open": false, "doi_is_click": false, "user_vars": {}, "bunce_log": null, "tags": [], "categories": [], "created": "2025-10-23T17:19:02.635703" } ``` #### Массовое обновление подписчиков `PATCH https://mailganer.com/api/v2/emails/mass/` · operationId: `updateSubscribersBulk` Обновляет до 50 подписчиков за один запрос. Тело — JSON-массив объектов. Операция атомарна. **Эндпоинт:** `PATCH https://mailganer.com/api/v2/emails/mass/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` ##### Тело запроса Массив объектов; поля каждого объекта: | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `email` | string | да | Имейл подписчика | | `source` | int / array / `"all"` | да | ID списка (узнать ID: https://mailganer.com/app/settings/); можно передать несколько или `"all"` | | `phone` | string | нет | Телефон | | `name` | string | нет | Имя | | `surname` | string | нет | Фамилия | | `patronymic` | string | нет | Отчество | | `gender` | int | нет | 1 — мужской, 2 — женский | | `birthday` | string | нет | Дата рождения, формат `dd.mm.yyyy` | | `city` | string | нет | Город | | `add_tag` | string / array | нет | Добавить метку | | `delete_tag` | string | нет | Удалить метку | | `user_vars` | object | нет | Пользовательские переменные; чтобы удалить значение переменной — передайте `null` | | `not_doi` | bool | нет | Отменяет отправку письма подтверждения; имейл добавляется в статусе «Активен» | | `need_activate` | bool | нет | Отправляет письмо подтверждения, даже если имейл в статусе «Запрошено подтверждение» | | `add_category` | string | нет | Добавить категорию подписки | | `delete_category` | string | нет | Удалить категорию подписки | | `email_status` | string | нет | Изменить статус. Значение `unsubscribe` меняет статус подписчика с «Активен» на «Отписался» | ##### Пример curl ```bash curl --location --request PATCH 'https://mailganer.com/api/v2/emails/mass/' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data-raw '[ { "email": "test@example.com", "source": 49767, "name": "Федор", "surname": "Федоров" } ]' ``` ##### Примечания - Максимум **50** имейлов за запрос. - Атомарность: если хотя бы в одном имейле есть ошибка, **ни один** имейл из пакета не будет обновлён. - `source` принимает: одиночный ID, массив ID или `"all"` (все списки). - В ответе по каждому имейлу возвращаются `id` и `mg_hash`. **Ответы:** `200` Успех (200), `400` Ошибка (400) Пример ответа `200`: ```json [ { "id": 45764030, "mg_hash": "100330457640309ee63894dced455d110aebcb2b" }, { "id": 45764025, "mg_hash": "e031e245764025457cb340b96fd670419cf95bb2" } ] ``` #### Массовое добавление подписчиков (v3) `POST https://mailganer.com/api/v3/emails/` · operationId: `createSubscribersV3` Добавляет подписчиков пачкой и возвращает подробный ответ: по каждой записи видно, добавилась она или нет и почему. **Эндпоинт:** `POST https://mailganer.com/api/v3/emails/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` Тело запроса — массив объектов подписчиков. Одиночный объект без массива метод тоже принимает. ##### Лимиты - Не больше 2000 запросов в минуту на аккаунт, при превышении вернётся `429`. - Жёсткого ограничения на размер пачки нет, но разумный размер — до нескольких сотен записей: ответ содержит полную карточку каждого добавленного подписчика. ##### Особенности - Пустая строка в необязательном поле равнозначна тому, что поле не передано: сохранённое значение не затирается. Незнакомые ключи игнорируются. - Если в `source` передан массив или `"all"`, подписчик создаётся в каждом списке, но в ответе придёт одна запись — по последнему обработанному списку. - Даты в переменных: dd.mm.yyyy, dd-mm-yyyy, yyyy.mm.dd, yyyy-mm-dd; дата-время — те же форматы плюс ЧЧ:ММ или ЧЧ:ММ:СС. Минимальный год 1900. Логические переменные принимают да/true/yes и нет/false/no в любом регистре. - Повторная отправка того же имейла в тот же список ошибкой не считается: подписчик обновляется и приходит в `successful`. ##### Ответ Ответ всегда содержит три массива: `successful` (добавлены), `failed` (не добавлены, в `errors` причина по каждому параметру), `warnings` (добавлены, но часть данных не записалась — чаще всего переменная не заведена в списке). | Код | Когда | |---|---| | `201` | Все записи добавлены, ошибок и предупреждений нет | | `207` | Часть записей не добавлена (непустой `failed`) или есть предупреждения (непустой `warnings`) | | `401` | Ключ API не передан или неверен, тело ответа пустое | | `429` | Превышен лимит 2000 запросов в минуту | | `503` | Сервис временно не смог обработать запрос, повторите через небольшую паузу | ##### Предупреждения по переменным | Когда возникает | Текст | |---|---| | Переменной нет в списке | Переменная "имя" не найдена и была пропущена. | | В целочисленную переменную передано не целое число | Значение "..." не является целым числом и было пропущено. | | В числовую переменную передано не число | Значение "..." не является числом и было пропущено. | | Некорректная дата или год меньше 1900 | Значение "..." не является корректной датой и было пропущено. | | Некорректная дата-время | Значение "..." не является корректной датой/временем и было пропущено. | | Логическое значение не из списка да/true/yes/нет/false/no | Значение "..." не является логическим значением и было пропущено. | | Строка не является корректным JSON (JSON-переменная) | Значение "..." не является корректным JSON и было пропущено. | | В значении найден html, а html не включён | В значении переменной "имя" обнаружен html-код; значение не записано. | ##### Возможные ошибки - `400` We have already sent a subscription confirmation email to this email. Resending is possible in 1 hour. — слишком много запросов на реактивацию имейла, повтор через час. - Email to many add method — при частых запросах второй запрос на тот же имейл не дождался обработки первого. ##### Пример curl ```bash curl --location --request POST 'https://mailganer.com/api/v3/emails/' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data-raw '[ {"email": "test1@example.com", "source": 49767}, {"email": "test2@example.com", "source": 49767} ]' ``` **Ответы:** `201` Все записи добавлены, `207` Часть записей не добавлена или есть предупреждения, `401` Ключ API не передан или неверен, тело пустое, `429` Превышен лимит 2000 запросов в минуту, `503` Сервис временно недоступен, повторите запрос позже Пример ответа `201`: ```json { "successful": [ { "id": 48744043, "mg_hash": "6b36dc48744043ec34ab9613c7f165b3e60f54f4", "email": "test1@example.com", "source": 49767, "email_status": "wait_activated", "corrected_email": "test1@example.com", "name": "Федор", "patronymic": "Федорович", "surname": "Федоров", "gender": 1, "birthday": "01.01.1988", "phone": "79123456789", "city": null, "country": null, "is_valid": false, "doi_is_delivery": false, "doi_is_open": false, "doi_is_click": false, "user_vars": {}, "bunce_log": null, "tags": [ "клиент" ], "categories": [ "новости" ], "created": "2026-07-28T12:59:39.399936", "modified": "2026-07-28T12:59:39.459810" } ], "failed": [], "warnings": [] } ``` ### Списки Работа со списками рассылки и их настройками #### Получить массив списков `GET https://mailganer.com/api/v2/sites/` · operationId: `listLists` Возвращает постраничный массив списков рассылки аккаунта. **Эндпоинт:** `GET https://mailganer.com/api/v2/sites/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` ##### Query-параметры | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `simple` | bool | нет | Если `true`, возвращаются только основные поля (`id` и `domain`). По умолчанию `false` | ##### Пример curl ```bash curl --location --request GET 'https://mailganer.com/api/v2/sites/' \ --header 'Authorization: CodeRequest {{api_key}}' ``` ##### Примечания - Ответ постраничный: поля `count`, `next`, `previous`, `results`. - Стандартный элемент `results` содержит: `id`, `domain`, `domain_ext`, `logo`, `user`, `click_domain`, `count_emails`, `count_emails_active`. - При `simple=true` элемент `results` содержит только `id` и `domain`. **Ответы:** `200` Success Пример ответа `200`: ```json { "count": 1, "next": null, "previous": null, "results": [ { "id": 60968, "domain": "mailagner.com", "domain_ext": "", "url": "", "logo": null, "user": 10912, "source_type": 3, "source": 1, "active": true, "click_domain": "click.mailagner.com" } ] } ``` #### Создать список `POST https://mailganer.com/api/v2/sites/` · operationId: `createList` Создаёт новый список рассылки. **Эндпоинт:** `POST https://mailganer.com/api/v2/sites/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` ##### Тело запроса | Поле | Тип | Обяз. | Описание | | --- | --- | --- | --- | | `domain` | string | да | Название списка | ##### Пример curl ``` bash curl --location --request POST 'https://mailganer.com/api/v2/sites/' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "domain": "test2" }' ``` ##### Примечания - В ответе возвращается объект созданного списка, включая его `id`. - Поле `domain` не должно содержать недопустимые символы (например `<`, `>`). - Комбинация полей `domain` и `user` должна быть уникальной (иначе `non_field_errors`). **Ответы:** `201` Success, `400` Ошибка (4xx), `401` Error - Недопустимый токен Пример ответа `201`: ```json { "id": 60968, "domain": "test8", "domain_ext": "", "url": "", "logo": null, "user": 10912, "source_type": 3, "source": 1, "active": true, "click_domain": "click." } ``` #### Проверка верификации домена `GET https://mailganer.com/api/v2/sites/verify_domain/` · operationId: `verifyListDomain` Проверяет статус верификации домена списка (SPF, DMARC, DKIM). **Эндпоинт:** `GET https://mailganer.com/api/v2/sites/verify_domain/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` ##### Query-параметры | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `domain` | string | да | Домен, который необходимо проверить | ##### Пример curl ```bash curl --location --request GET 'https://mailganer.com/api/v2/sites/verify_domain/?domain=mailganer.com' \ --header 'Authorization: CodeRequest {{api_key}}' ``` ##### Примечания - Ответ содержит булевы поля: `verification_status` (общий статус верификации), `spf_status`, `dmarc_status`, `dkim_status`. **Ответы:** `200` Success Пример ответа `200`: ```json { "verification_status": true, "spf_status": true, "dmarc_status": true, "dkim_status": true } ``` #### Задать ссылку на webhook `POST https://mailganer.com/api/v2/sites/set_webhook` · operationId: `setListWebhook` Задаёт (или обновляет) URL webhook для списка и параметры его работы. **Эндпоинт:** `POST https://mailganer.com/api/v2/sites/set_webhook` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` ##### Тело запроса | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `id` | string | да | ID списка (можно узнать в настройках списка: https://mailganer.com/app/settings/) | | `url` | string | да | URL, на который отправляются события (webhook) | | `is_active` | bool | нет | Включает/отключает отправку событий на webhook | | `is_use_auth_key` | bool | нет | Включает/отключает отправку ключа авторизации в заголовке `Authorization` | | `is_enable_retry` | bool | нет | Включает/отключает повторы, если URL хука недоступен | ##### Пример curl ```bash curl --location --request POST 'https://mailganer.com/api/v2/sites/set_webhook' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "id": 1008, "url": "https://webhook.site/example", "is_active": true, "is_use_auth_key": true, "is_enable_retry": false }' ``` ##### Примечания - Повторы (`is_enable_retry`) выполняются тремя попытками при ошибке эндпоинта: через 5 секунд, 1 час и 24 часа. - Активировать webhook также можно в настройках списка на вкладке «Интеграции». - При `is_use_auth_key=true` ключ авторизации передаётся в заголовке `Authorization`. **Ответы:** `200` Успех (200) Пример ответа `200`: ```json { "id": 1008, "is_active": true, "url": "https://webhook.site/b27b31cd-1fc9-48df-be47-4e2678546ca241b", "is_use_auth_key": true, "is_enable_retry": false } ``` ##### Вебхук: Изменение статуса подписчика Событие изменения статуса подписки подписчика (`type=1`). **Входящий вебхук** — Mailganer отправляет POST на ваш URL, заданный методом «Задать ссылку на webhook». **Метод доставки:** POST **Content-Type:** application/x-www-form-urlencoded (form-values) ###### Поля payload | Поле | Тип | Описание | | --- | --- | --- | | `type` | int | Тип вебхука, всегда `1` для изменения статуса подписчика | | `email` | string | Имейл подписчика | | `status` | int | Числовой статус подписки (см. таблицу статусов ниже) | | `status_message` | string | Текстовая расшифровка (например, причина недоставки) | | `timestamp` | string | Дата и время отправки вебхука | | `source_id` | int | ID списка. Передаётся не для всех событий (только при спаме/отписке) | | `source_name` | string | Название списка. Передаётся не для всех событий (только при спаме/отписке) | | `method` | string | `spam` или `unsubscribe`. Передаётся не для всех событий | | `reason` | string | Причина отписки. Передаётся только для событий отписки | ###### Значения `status` | Значение | Описание | | --- | --- | | `-6` | Исправлен (при импорте найдены недопустимые символы) | | `-5` | Исправлен (опечатка исправлена системой) | | `-4` | Помечен как спам сервером | | `-3` | Помечен как спам пользователем | | `-2` | Недоступен | | `-1` | Отписан от рассылок | | `0` | Новый | | `1` | Активен | | `2` | Запрошено подтверждение | ###### Пример payload ``` status=-1&source_name=%D0%A2%D0%B5%D1%81%D1%82+%D1%85%D1%83%D0%BA%D0%B0&source_id=1092359×tamp=2026-05-19+15%3A26%3A19.654599&type=1&method=unsubscribe&email=example%40example.com ``` ###### Примечания - Хук активируется в настройках списка на вкладке «Интеграции». - Опциональный переключатель добавляет в запрос заголовок с ключом авторизации. - Поля `source_id`, `source_name`, `method` передаются не для всех событий — только когда пользователь пожаловался на спам или отписался. Поле `reason` присутствует только для отписки. - Повторные попытки при ошибке на вашем эндпоинте: через 5 секунд, 1 час и 24 часа. ##### Вебхук: Изменение данных о подписчике Событие изменения данных в карточке подписчика (`type=2`). Хук отправляется каждый раз, когда изменяется какое-либо поле в карточке подписчика. **Входящий вебхук** — Mailganer отправляет POST на ваш URL, заданный методом «Задать ссылку на webhook». **Метод доставки:** POST **Content-Type:** application/x-www-form-urlencoded (form-values) ###### Поля payload | Поле | Тип | Описание | | --- | --- | --- | | `type` | int | Тип вебхука, всегда `2` для изменения данных о подписчике | | `src` | int | Источник изменения: `1` — изменение через API, `2` — изменение через интерфейс | | `email` | string | Имейл подписчика | | `birthday` | date | Дата рождения, формат `YYYY-MM-DD` | | `user_vars` | array | Пользовательские переменные в формате `[['variable_name', 'value'], ['variable_name2', 'value']]` | ###### Пример payload ``` type=2&src=2&email=example%40mail.ru&birthday=1988-01-01 ``` ###### Примечания - В документации нет готового примера payload; тело выше собрано из перечня документированных полей с иллюстративными значениями-заглушками. - Хук активируется в настройках списка на вкладке «Интеграции». - Опциональный переключатель добавляет в запрос заголовок с ключом авторизации. - Хук срабатывает только при фактическом изменении данных. - Пользовательские переменные (`user_vars`) передаются парами «имя — значение» в виде массива. - Повторные попытки при ошибке на вашем эндпоинте: через 5 секунд, 1 час и 24 часа. ##### Вебхук: Взаимодействие с письмом Событие взаимодействия с письмом в массовой или триггерной рассылке (`type=3`). Срабатывает на каждое сообщение при любом взаимодействии с ним. **Входящий вебхук** — Mailganer отправляет POST на ваш URL, заданный методом «Задать ссылку на webhook». **Метод доставки:** POST **Content-Type:** application/x-www-form-urlencoded (form-values) ###### Поля payload | Поле | Тип | Описание | | --- | --- | --- | | `type` | int | Тип вебхука, всегда `3` для взаимодействия с письмом | | `email` | string | Имейл получателя | | `source` | int | ID списка, которому принадлежит письмо | | `action` | int | Тип взаимодействия (см. таблицу значений ниже) | | `timestamp` | string | Дата и время взаимодействия | | `mail_type` | string | `mailing` (массовая рассылка) или `trigger` (триггерное сообщение) | | `public_id` | string | Публичный ID массовой/триггерной рассылки | | `mail_id` | string | ID отправки сообщения (для триггерных рассылок) | | `trigger_id` | string | ID триггера в системе Mailganer | ###### Значения `action` | Значение | Описание | | --- | --- | | `-3` | Не доставлено | | `-2` | Жалоба на спам | | `-1` | Отписка | | `1` | Доставлено | | `2` | Открытие письма | | `3` | Клик по ссылке в письме | ###### Значения `mail_type` | Значение | Описание | | --- | --- | | `mailing` | Взаимодействие из вручную отправленной массовой рассылки | | `trigger` | Взаимодействие из триггерного сообщения | ###### Пример payload ``` mail_id=999129235&public_id=166118134802&mail_type=mailing&action=1×tamp=2022-08-22+15%3A18%3A44.960548&type=3&email=example%40mail.ru ``` ###### Примечания - Хук активируется в настройках списка на вкладке «Интеграции». - Опциональный переключатель добавляет в запрос заголовок с ключом авторизации. - Повторные попытки при ошибке на вашем эндпоинте: через 5 секунд, 1 час и 24 часа. ##### Вебхук: Срабатывание события в триггере Событие срабатывания триггера (`type=4`). Используется, когда нужно передать информацию во внешнюю систему вместе с отправкой письма или передать данные без отправки письма. **Входящий вебхук** — Mailganer отправляет POST на ваш URL, заданный методом «Задать ссылку на webhook». **Метод доставки:** POST **Content-Type:** application/x-www-form-urlencoded (form-values) ###### Поля payload | Поле | Тип | Описание | | --- | --- | --- | | `type` | int | Тип вебхука, всегда `4` для срабатывания события в триггере | | `public_id` | int | ID триггера | | `email` | string | Имейл подписчика | | `phone` | string | Телефон | | `name` | string | Имя | | `surname` | string | Фамилия | | `patronymic` | string | Отчество | | `gender` | int | Пол: `1` — мужской, `2` — женский | | `birthday` | date | Дата рождения, формат `dd.mm.yyyy` | | `city` | string | Город | | `user_var_{имя_переменной}` | string | Пользовательские переменные передаются как `user_var_{имя_переменной}` (например, `user_var_company_name`) | ###### Пример payload ``` type=4&public_id=166118134802&email=example%40mail.ru&phone=%2B79123456789&name=%D0%A4%D0%B5%D0%B4%D0%BE%D1%80&surname=%D0%A4%D0%B5%D0%B4%D0%BE%D1%80%D0%BE%D0%B2&patronymic=%D0%A4%D0%B5%D0%B4%D0%BE%D1%80%D0%BE%D0%B2%D0%B8%D1%87&gender=1&birthday=01.01.1988&city=%D0%9C%D0%BE%D1%81%D0%BA%D0%B2%D0%B0&user_var_company_name=Ganer ``` ###### Примечания - В документации нет готового примера payload; тело выше собрано из перечня документированных полей с иллюстративными значениями-заглушками. - Хук активируется в настройках списка на вкладке «Интеграции». - Опциональный переключатель добавляет в запрос заголовок с ключом авторизации. - Пользовательские переменные передаются с префиксом `user_var_` в названии поля. - Повторные попытки при ошибке на вашем эндпоинте: через 5 секунд, 1 час и 24 часа. ### Сегменты Создание и получение сегментов подписчиков #### Получить массив сегментов `GET https://mailganer.com/api/v2/segments/` · operationId: `listSegments` Возвращает постраничный массив сегментов аккаунта. **Эндпоинт:** `GET https://mailganer.com/api/v2/segments/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` ##### Пример curl ```bash curl --location --request GET 'https://mailganer.com/api/v2/segments/' \ --header 'Authorization: CodeRequest {{api_key}}' ``` ##### Примечания - Ответ постраничный: поля `count`, `next`, `previous`, `results`; переход по страницам — через `next`/`previous` (параметр `page`). - Элемент `results` содержит: `title`, `id`, `cnt_email`, `cnt_active_email`, `created`. **Ответы:** `200` Success Пример ответа `200`: ```json { "count": 2, "next": "https://mailganer.com/api/v2/segments/?page=2", "previous": null, "results": [ { "title": "Название сегмента", "id": 1831, "cnt_email": 478, "cnt_active_email": 478, "created": "2017-05-27T17:35:04.713572" }, { "title": "Название сегмента 2", "id": 1832, "cnt_email": 478, "cnt_active_email": 478, "created": "2017-05-27T17:35:04.713572" } ] } ``` #### Создать сегмент `POST https://mailganer.com/api/v2/segments/` · operationId: `createSegment` Создаёт сегмент подписчиков по заданным условиям. **Эндпоинт:** `POST https://mailganer.com/api/v2/segments/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` ##### Тело запроса | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `title` | string | да | Название сегмента | | `conditions` | array | да | Массив условий сегментации | | `conditions[].condition` | int | да | Тип условия (например, `6` — «Метка», `5` — «Список») | | `conditions[].type_value` | int | да | Тип значения (`4` — «Равна одной из», `5` — «Не равна одной из») | | `conditions[].value` | array | да | Значения условия | ##### Пример curl ```bash curl --location --request POST 'https://mailganer.com/api/v2/segments/' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "title": "Тест API", "conditions": [ { "condition": 6, "type_value": 4, "value": ["Тег"] }, { "condition": 5, "type_value": 4, "value": ["51822"] } ] }' ``` ##### Примечания - В ответе возвращаются `status`, `segment_url` (ссылка на созданный сегмент) и `segment_id`. **Ответы:** `201` Success Пример ответа `201`: ```json { "status": "success", "segment_url": "https://mailganer.com/app/segment/edit/19254/", "segment_id": 19254 } ``` #### Получить информацию о сегменте `GET https://mailganer.com/api/v2/segments/{segment_id}` · operationId: `getSegment` Возвращает информацию об одном сегменте по его ID. **Эндпоинт:** `GET https://mailganer.com/api/v2/segments/:segment_id` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` ##### Path-параметры | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `segment_id` | int | да | ID сегмента | ##### Пример curl ```bash curl --location --request GET 'https://mailganer.com/api/v2/segments/12345' \ --header 'Authorization: CodeRequest {{api_key}}' ``` ##### Примечания - Ответ содержит: `title`, `id`, `cnt_email`, `cnt_active_email`, `created`. **Ответы:** `200` Success Пример ответа `200`: ```json { "title": "Название сегмента", "id": 12345, "cnt_email": 1, "cnt_active_email": 1, "created": "2022-12-05T11:26:44.465956" } ``` #### Отправка триггера на сегмент `POST https://mailganer.com/api/v2/segments/{segment_id}/send_trigger/` · operationId: `sendSegmentTrigger` Запускает отправку указанного триггера подписчикам сегмента. Можно отправить триггер с учётом его условий ("Когда отправить" и "Время отправки") или игнорируя их. **Эндпоинт:** `POST https://mailganer.com/api/v2/segments/:segment_id/send_trigger/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` Сегмент должен быть создан в личном кабинете и содержать условие "Список равен любому из" с одним списком. Этот список должен входить в списки подписчиков отправляемого триггера. Если список сегмента не входит в списки триггера, метод вернёт ошибку 400, отправка не будет создана. ##### Path-параметры | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `segment_id` | int | да | ID сегмента, по которому запускается триггер | ##### Тело запроса | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `trigger_id` | int | да | ID триггера, который необходимо отправить | | `ignore_trigger_conditions` | bool | нет | Если `true`, триггер отправляется сразу, условия игнорируются. По умолчанию `false`: отправка учитывает настройки триггера "Когда отправить" и "Время отправки" | ##### Пример curl ```bash curl --location --request POST 'https://mailganer.com/api/v2/segments/12345/send_trigger/' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "trigger_id": 34521 }' ``` ##### Примечания - Ответ `success` означает, что отправка поставлена в очередь, а не выполнена. Письма уходят фоном, между ответом и отправкой проходит время. Статус задачи проверяйте по `task_id` методом `GET /api/v2/tasks/:task_id`: пока `state` не станет `COMPLETED`, отправка не завершена. - Если список сегмента не входит в списки триггера, в ответе 400 указаны номер списка и номер триггера: `Please set the current site [номер списка] for the trigger [номер триггера]`. Добавьте этот список в подписчики триггера в настройках триггера или используйте сегмент со списком, который у триггера уже есть. - Другие ошибки 400: не передан `trigger_id`, триггер не найден (`Trigger does not exists`), в сегменте нет условия "Список равен любому из" или в нём выбрано несколько списков. Ошибка 404: сегмент не найден. - Актуальный список подписчиков определяется по состоянию сегмента на момент запуска. Отправка идёт только подписчикам в статусе "Активен". - Повторный вызов для того же сегмента не игнорируется: каждый вызов создаёт отдельную задачу со своим `task_id`, подписчики получат письмо по каждому вызову. Если запрос завершился по таймауту, сначала проверьте, что первая отправка не поставлена, иначе подписчики получат дубли. **Ответы:** `200` Отправка поставлена в очередь. Письма уходят фоном, статус задачи проверяется по `task_id`, `400` Не переданы обязательные поля, триггер не найден, в сегменте нет подходящего условия по списку или список сегмента не входит в списки триггера. Отправка не создаётся, `401` Ключ API не передан или неверен, `404` Сегмент не найден Пример ответа `200`: ```json { "status": "success", "message": "Trigger queued for sending", "data": { "segment_id": 300092, "segment_name": "Тестовый сегмент", "trigger_id": 20283, "trigger_name": "Тестовый триггер", "site_id": 113276, "ignore_conditions_and_time_send": false, "task_id": "caf07d14-7fa2-4cc8-9a2d-1149ff3369e7", "scheduled_at": "2026-09-30T15:24:14.975218" } } ``` ### Переменные Пользовательские переменные подписчиков #### Получить список пользовательских переменных `GET https://mailganer.com/api/v2/user_vars/` · operationId: `listUserVars` Возвращает список пользовательских переменных списка (или всех списков). **Эндпоинт:** `GET https://mailganer.com/api/v2/user_vars/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` ##### Query-параметры | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `source` | Целое число | — | ID списка. Если не указан — возвращаются переменные всех списков | ##### Пример curl ```bash curl --location 'https://mailganer.com/api/v2/user_vars/?source=1' \ --header 'Authorization: CodeRequest {{api_key}}' ``` ##### Примечания - Ответ постраничный: `count` (количество переменных), `next` / `previous` (ссылки на соседние страницы, `null` — если страницы нет), `results` (массив переменных). - Поля объекта в `results`: `source` (ID списка), `title` (название), `name` (системное имя для подстановки в шаблонах), `type` (тип), `is_global` (`false` — локальная, `true` — глобальная переменная). - По умолчанию API отдаёт по 25 записей на страницу. - Значения поля `type`: | id типа | Тип переменной | Пример | |---|---|---| | 0 | Строка | Текст | | 1 | Целое число | 12 | | 2 | Вещественное число | 1.5 | | 3 | Дата | 22.07.2021 | | 4 | Дата и время | 22.07.2021 16:03:00 | | 6 | Логический тип | true или false | | 8 | Json-массив | {"a": 1, "b": "два", "c": [1, 2]} | **Ответы:** `200` Успех (200) Пример ответа `200`: ```json { "count": 11, "next": null, "previous": null, "results": [ { "source": "1", "title": "Телефон", "name": "phone", "type": 0, "is_global": false }, { "source": "1", "title": "Имя", "name": "name", "type": 0, "is_global": false }, { "source": "1", "title": "Фамилия", "name": "lastname", "type": 0, "is_global": false }, { "source": "1", "title": "Отчество", "name": "patronymic", "type": 0, "is_global": false }, { "source": "1", "title": "Дата рождения", "name": "birthday", "type": 3, "is_global": false }, { "source": "1", "title": "Пол", "name": "gender", "type": 0, "is_global": false }, { "source": "1", "title": "Страна", "name": "country", "type": 0, "is_global": false }, { "source": "1", "title": "Город", "name": "city", "type": 0, "is_global": false }, { "source": "1", "title": "Дата подписки", "name": "subscribe_date", "type": 3, "is_global": false }, { "source": 1, "title": "float", "name": "float", "type": 2, "type_text": "Вещественное число" }, { "source": 1, "title": "datetime", "name": "datetime", "type": 4, "type_text": "Дата и время" } ] } ``` #### Добавление пользовательской переменной `POST https://mailganer.com/api/v2/user_vars/` · operationId: `createUserVar` Добавляет пользовательскую переменную в указанный список. **Эндпоинт:** `POST https://mailganer.com/api/v2/user_vars/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` ##### Тело запроса | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `source` | Целое число | ✔ | ID списка, в который добавляется переменная | | `title` | Строка | ✔ | Название переменной | | `type` | Целое число | ✔ | Тип переменной (допустимые значения — в таблице ниже) | | `name` | Строка | — | Имя переменной. Если не задано, формируется автоматически и возвращается в ответе | ##### Пример curl ```bash curl --location 'https://mailganer.com/api/v2/user_vars/' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data '{ "source": 1, "title": "Название переменной", "type": 0 }' ``` ##### Примечания - Значения поля `type`: | id типа | Тип переменной | Пример | |---|---|---| | 0 | Строка | Текст | | 1 | Целое число | 12 | | 2 | Вещественное число | 1.5 | | 3 | Дата | 22.07.2021 | | 4 | Дата и время | 22.07.2021 16:03:00 | | 6 | Логический тип | true или false | | 8 | Json-массив | {"a": 1, "b": "два", "c": [1, 2]} | - Ответ содержит поля: `source` (ID списка), `title` (название), `name` (имя переменной), `type` (тип), `type_text` (тип текстом). **Ответы:** `400` Не переданы обязательные поля, `401` Ключ API не передан или неверен, `2XX` Переменная создана ### Теги Управление тегами подписчиков #### Получить список тегов `GET https://mailganer.com/api/v2/tags/` · operationId: `listTags` Возвращает список тегов. **Эндпоинт:** `GET https://mailganer.com/api/v2/tags/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` ##### Пример curl ```bash curl --location 'https://mailganer.com/api/v2/tags/' \ --header 'Authorization: CodeRequest {{api_key}}' ``` ##### Примечания - Ответ постраничный: `count` (количество тегов), `next` / `previous` (ссылки на соседние страницы), `results` (массив тегов). - Поля объекта в `results`: `id` (идентификатор тега), `name` (название тега). **Ответы:** `200` Успех (200) Пример ответа `200`: ```json { "count": 4, "next": null, "previous": null, "results": [ { "id": 28174, "name": "название_тега2" }, { "id": 28173, "name": "название_тега" }, { "id": 28172, "name": "test" }, { "id": 28171, "name": "тест" } ] } ``` #### Добавление тега `POST https://mailganer.com/api/v2/tags/` · operationId: `createTag` Добавляет новый тег. **Эндпоинт:** `POST https://mailganer.com/api/v2/tags/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` ##### Тело запроса | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `name` | Строка | ✔ | Имя тега. Длина не более 140 символов | ##### Пример curl ```bash curl --location 'https://mailganer.com/api/v2/tags/' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data '{ "name": "название_тега" }' ``` ##### Примечания - Ответ содержит поля: `id` (идентификатор тега), `name` (имя тега). - Возможные ошибки: - `400 — The selected tag name is already in use` — тег с таким названием уже есть в системе. - `400 — The tag name must not exceed 140 characters` — длина `name` более 140 символов. **Ответы:** `200` Успех (200) Пример ответа `200`: ```json { "id": 28174, "name": "название_тега" } ``` ### Рассылки Создание, отправка и статистика рассылок #### Создание рассылки `POST https://mailganer.com/api/v1/mailing/create/` · operationId: `createMailing` Создаёт черновик рассылки — возвращает ссылку на редактирование и `public_id`. **Эндпоинт:** `POST https://mailganer.com/api/v1/mailing/create/` **Авторизация:** `noauth` — API-ключ передаётся в теле запроса в поле `api_key` **Content-Type:** `multipart/form-data` (form-data) ##### Тело запроса (form-data) | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `api_key` | string | ✔ | Ключ API из профиля | | `name` | string | | Название рассылки, максимум 150 символов | | `html-content` | string | | Вёрстка рассылки | | `template_id` | string | | UID шаблона со страницы `https://mailganer.com/app/custom-templates/` | | `amp-html-content` | string | | Вёрстка AMP-рассылки | | `zip-content` | string | | Ссылка на архив с вёрсткой | | `amp-zip-content` | string | | Ссылка на архив с AMP-вёрсткой | | `theme` | string | | Тема рассылки | | `from_name` | string | | Имя отправителя | | `from_email` | string | | Имейл отправителя | | `segment_id` | int | | ID сегмента | | `utm_campaign` | string | | Если не передано — формируется как `{{year}}{{month}}{{day}}_{{public_id}}` (год, месяц, день отправки и ID рассылки) | | `utm_source` | string | | Если не передано — `"mailganer"` | | `utm_medium` | string | | Если не передано — `"email"` | | `user_utms` | JSON-строка | | Кастомные UTM-метки, формат `{"param1":"value1","param2":"value2"}` | | `variables` | JSON-строка | | Динамические переменные, формат `{"var1":"value1","var2":123}`; имеют приоритет над переменными подписчика | ##### Пример curl ```bash curl --location 'https://mailganer.com/api/v1/mailing/create/' \ --form 'api_key="XXX"' \ --form 'name="Новая рассылка"' \ --form 'theme="Theme"' \ --form 'from_email="info@example.com"' \ --form 'from_name="info@example.com"' \ --form 'utm_campaign="summer_sale"' \ --form 'utm_source="newsletter"' \ --form 'utm_medium="email"' \ --form 'user_utms="{\"promo\":\"summer2025\",\"location\":\"europe\"}"' \ --form 'zip-content="https://cdn.mailganer.com/mailing-template/demo.zip"' ``` ##### Примечания - В вёрстке письма можно одновременно использовать переменные из запроса (`variables`) и переменные подписчика (например `{{name}}`); значение, не обязательное для хранения в Mailganer (например `delivery_address`), можно передать в запросе и подставить как `{{delivery_address}}`. - При передаче вёрстки в `html-content` заменить символы: `&`→`%26`, `"`→`%22`, `\`→`%27`, `<`→`%3C`, `>`→`%3E`. - Архив в `zip-content` — только `.zip`; размер архива должен быть более 7 Мб; внутри обязателен html-файл. - Поля ответа: `status` (1 — успех, -1 — нет), `status_text` (`success`/`error`), `public_id`, `step1_url`, `error`. - Возможные значения `error`: `Invalid api key`; `Invalid http method`; `Invalid url`; `file недоступен`; `Zip-files only is allowed`; `Filesize must be more than 7 Mb`; `HTML template file not found`; `email the sender is not confirmed`; `segment_id does not exists`; `Invalid JSON decoded variables: No JSON object could be decoded`; `HTML and JavaScript are not allowed in variables for security reasons`. **Ответы:** `200` Success Пример ответа `200`: ```json { "status": 1, "step1_url": "https://mailganer.com/app/mailing/step1/155959878052/", "status_text": "success", "public_id": 155959878052 } ``` #### Отправка рассылки `POST https://mailganer.com/api/v2/mailing/send/` · operationId: `sendMailing` Отправляет рассылку — сразу или в запланированное время. **Эндпоинт:** `POST https://mailganer.com/api/v2/mailing/send/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` ##### Тело запроса | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `public_id` | int | ✔ | ID рассылки | | `datetime_send` | string | | Дата/время отправки в формате `DD.MM.YYYY HH:MM`, например `16.02.2024 17:00` | | `is_chunked` | bool | | Включить распределённую отправку. Для сегментов больше 5 000 получателей. Недоступно при A/Б тестировании темы письма | | `chunk_size` | int | | Количество подписчиков в одной отправке. Значения вне допустимого диапазона система может скорректировать самостоятельно | | `chunk_timeout` | int | | Перерыв между отправками. Разрешённые значения: `15`, `30`, `60`, `90` минут | ##### Пример curl ```bash curl --location 'https://mailganer.com/api/v2/mailing/send/' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data '{ "public_id": 155959878052, "datetime_send": "16.02.2024 17:00" }' ``` ##### Примечания - Параметры `chunk_size` и `chunk_timeout` требуют `is_chunked=True` (иначе ошибка `Parameters 'chunk_size' and 'chunk_timeout' require 'is_chunked=True'`). - Поля ответа: `статус` (`success`), `status_text` (`Mailing has been sent for moderation` или `Mailing has been sent`), `error`. - Возможные значения ошибок (`error` / `status_text`): `Mailing has been sent` (рассылка отправлена); `Mailing is delivered` (рассылка доставлена); `Mailing has an invalid status for sending` (невалидный статус для отправки); `Mailing subject is empty` (тема пустая); `Change default subject name` (дефолтная тема); `Mailing content is empty` (контент пустой); `Sender email not verified` (email отправителя не верифицирован); `Must define unsubscribe link in mailing content` (нет ссылки на отписку); `Not activate tariff` (тариф не активирован); `Tariff limit exceeded` (превышен тарифный лимит); `Parameters 'chunk_size' and 'chunk_timeout' require 'is_chunked=True'`. - Возможные ошибки уровня запроса: `invalid http method` (метод не POST); `invalid post values` (не задана обязательная переменная); `invalid api key` (неправильный апи-ключ). **Ответы:** `200` Success Пример ответа `200`: ```json { "статус": "success", "status_text": "Mailing has been sent for moderation" } ``` #### Получение информации о рассылке `GET https://mailganer.com/api/v2/mailing/{public_id}` · operationId: `getMailing` Возвращает подробную информацию о конкретной рассылке. **Эндпоинт:** `GET https://mailganer.com/api/v2/mailing/:public_id` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` ##### Path-параметры | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `public_id` | int | ✔ | ID рассылки | ##### Пример curl ```bash curl --location 'https://mailganer.com/api/v2/mailing/166775985258' \ --header 'Authorization: CodeRequest {{api_key}}' ``` ##### Примечания Поля ответа (json): - `public_id` (int) — ID рассылки - `datetime_send` (string) — время отправки (datetime) - `send` (string) — время отправки - `name` (string) — название рассылки - `subject` (string) — тема рассылки - `subject2` (string) — вторая тема рассылки (актуально для А/Б-тестов) - `segment_name` (string) — название сегмента - `segment_id` (int) — ID сегмента - `from_name` (string) — имя отправителя - `from_email` (string) — имейл отправителя - `utm_campaign` (string) — значение URL-параметра utm_campaign - `utm_source` (string) — значение URL-параметра utm_source - `utm_medium` (string) — значение URL-параметра utm_medium - `text` (string) — HTML-контент письма в виде строки - `count_spam` (int) — количество жалоб на спам - `count_unsubscribe` (int) — количество отписок - `count_click` (int) — количество кликов - `count_open` (int) — количество открытий - `count_delivery` (int) — количество доставленных писем - `count_sent` (int) — количество отправленных писем - `webversion` (string) — ссылка на вебверсию письма - `user_utms` (array) — пользовательские переменные - `preheader` (string) — прехедер письма - `clickmap` (string) — ссылка на карту кликов **Ответы:** `201` Получение информации о рассылке Пример ответа `201`: ```json { "public_id": 166775985258, "datetime_send": "07.11.2022 03:37", "send": "2022-11-07T03:37:02.141548", "name": "Mailing Name", "subject": "Email subject", "segment_name": "Segment Name", "segment_id": 7502, "from_name": "Sender Name", "from_email": "info@mailganer.com", "utm_campaign": "166775985258", "utm_source": "mailganer", "utm_medium": "email", "text": "HTML Content", "count_spam": 1, "count_unsubscribe": 14, "count_click": 448, "count_open": 1489, "count_delivery": 13348, "webversion": "https://click.mailganer.com/webversion/166775985258/", "user_utms": { "custom_param_1": "{{custom_param_1}}" } } ``` #### Получить список рассылок `GET https://mailganer.com/api/v2/mailing/` · operationId: `listMailings` Возвращает список рассылок за указанный период. **Эндпоинт:** `GET https://mailganer.com/api/v2/mailing/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` ##### Query-параметры | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `start_date` | date | | Дата начала периода, за который возвращать список рассылок | | `end_date` | date | | Дата окончания периода, за который возвращать список рассылок | ##### Пример curl ```bash curl --location 'https://mailganer.com/api/v2/mailing/?start_date=2024-04-01&end_date=2024-04-13' \ --header 'Authorization: CodeRequest {{api_key}}' ``` ##### Примечания Поля ответа (json): - `count` (int) — количество пользователей - `next` (url) — ссылка на следующую страницу - `previous` (url) — ссылка на предыдущую страницу - `results` (json-массив) — список рассылок Содержимое массива `results`: - `datetime_send` (дата и время) — планируемое время отправки - `send` (дата и время) — время начала отправки - `count_sent` (int) — получателей в рассылке - `count_delivery` (int) — доставленных писем - `count_spam` (int) — жалоб на спам - `count_unsubscribe` (int) — отписались - `count_click` (int) — кликнули в рассылке - `count_open` (int) — открыли - `public_id` (int) — ID рассылки - `Created` (дата и время) — дата создания рассылки - `name` (string) — название рассылки - `subject` (string) — тема рассылки - `subject2` (string) — вторая тема рассылки - `preheader` (string) — прехедер - `segment_name` (string) — название сегмента - `segment_id` (int) — ID сегмента - `excluding_segments` (int) — ID исключающего сегмента - `from_name` (string) — имя отправителя - `from_email` (string) — email отправителя - `text` — HTML-код верстки письма - `webversion` (url) — веб-версия письма - `clickmap` (url) — карта кликов - `status_str` (string) — статус рассылки **Ответы:** `401` Ошибка #### Статистика по рассылке `GET https://mailganer.com/api/v2/mailing/{public_id}/stat/` · operationId: `getMailingStats` Возвращает статистику по рассылке — в разрезе дней и суммарно за период. **Эндпоинт:** `GET https://mailganer.com/api/v2/mailing/:public_id/stat/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` ##### Path-параметры | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `public_id` | int | ✔ | ID рассылки | ##### Query-параметры | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `start_date` | string | | Дата начала в формате `YYYY-MM-DD` | | `end_date` | string | | Дата конца в формате `YYYY-MM-DD` | ##### Пример curl ```bash curl --location 'https://mailganer.com/api/v2/mailing/459562475965/stat/?start_date=2023-12-11&end_date=2023-12-13' \ --header 'Authorization: CodeRequest {{api_key}}' ``` ##### Примечания - Если параметры не указаны — возвращается общая статистика по рассылке за каждый день, а также суммарная статистика за весь период. - Если один из параметров `start_date`/`end_date` не указан — возвращается общая статистика за каждый день плюс суммарная за весь период. - Если указаны обе даты — возвращаются данные за указанный период (включая последний день) в разрезе дней плюс суммарная за период статистика. Поля ответа (json): - `count_sent` — отправлено - `count_delivery` — доставлено - `count_spam` — пожаловались на спам - `count_unsubscribe` — отписались - `count_click` — кликнули - `count_open` — открыли **Ответы:** `200` Success Пример ответа `200`: ```json [ { "2024-06-14": { "count_sent": 4907, "count_delivery": 3683, "count_spam": 0, "count_unsubscribe": 0, "count_click": 0, "count_open": 0 } }, { "2024-06-15": { "count_sent": 4907, "count_delivery": 3683, "count_spam": 0, "count_unsubscribe": 0, "count_click": 0, "count_open": 0 } }, { "2024-06-16": { "count_sent": 4907, "count_delivery": 3683, "count_spam": 0, "count_unsubscribe": 0, "count_click": 0, "count_open": 0 } }, { "2024-06-17": { "count_sent": 4907, "count_delivery": 3683, "count_spam": 0, "count_unsubscribe": 0, "count_click": 0, "count_open": 0 } }, { "2024-06-18": { "count_sent": 4907, "count_delivery": 3683, "count_spam": 0, "count_unsubscribe": 0, "count_click": 0, "count_open": 0 } }, { "summary": { "count_sent": 4907, "count_delivery": 3683, "count_spam": 0, "count_unsubscribe": 1, "count_click": 47, "count_open": 265 } } ] ``` ### Триггеры Триггерные механики, их отправка и статистика #### Отправка триггера `POST https://mailganer.com/api/v2/triggers/{trigger_id}/send/` · operationId: `sendTrigger` Отправляет триггерное письмо (или SMS) конкретному подписчику по его имейлу. **Эндпоинт:** `POST https://mailganer.com/api/v2/triggers/:trigger_id/send/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` ##### Path-параметры | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `trigger_id` | int | Да | ID триггера | ##### Тело запроса | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `email` | string | Да | Имейл получателя | | `phone` | string | Нет | Телефон получателя (для SMS-триггера) | | `trigger_content` | string | Нет | Своё содержимое письма (UTF-8), переопределяет контент из кабинета | | `trigger_theme` | string | Нет | Своя тема письма (UTF-8), переопределяет тему из кабинета | | `ignore_wait` | bool | Нет | Отправить, несмотря на статус «ожидает подтверждения» | | `ignore_unsubscribed` | bool | Нет | Отправить, несмотря на статус «отписан» | | `ignore_spam` | bool | Нет | Отправить, несмотря на жалобу на спам | | `doi_ok` | bool | Нет | Добавить подписчика как «Активный» перед отправкой | | `send_now` | bool | Нет | Игнорировать настройку отложенной отправки | | `variables` | array/object | Нет | Переменные шаблона письма (одномерные и многомерные массивы) | | `update_variables` | bool | Нет | Обновить переменные подписчика (требует активации) | | `sender_email` | string | Нет | Свой адрес отправителя (требует `sender_name`) | | `sender_name` | string | Нет | Имя отправителя в поле From | ##### Пример curl ```bash curl --location 'https://mailganer.com/api/v2/triggers/1111/send/' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "test@example.com" }' ``` ##### Примечания - Рекомендуемая частота вызовов — **не более 300 в минуту**. - `variables` поддерживает одномерные и многомерные массивы; язык шаблонов — Django-подобный синтаксис с операторами `{% for %}`, `{% if %}`. - Нельзя размещать `{% for %}` или `{% if %}` между тегами `` и `
`. - `sender_email` принимается только если отправитель существует в аккаунте и подтверждён (верифицирован). - По умолчанию `doi_ok`, `ignore_unsubscribed`, `ignore_spam`, `update_variables` отключены — активация через поддержку. - Ответ: `status` (1 — отправлено, -1 — ошибка, 0 — системная ошибка), `status_text` (`success`/`error`), `result` (уникальный ID отправки для запроса статистики), `error` (описание ошибки). - Возможные ошибки: `Invalid post values` (нет обязательного параметра), `Invalid email value` (некорректный имейл), `Error api key` (неверный ключ), `Not activate tariff` (тариф не активен), `Tariff limit exceeded` (исчерпан лимит), `Not found trigger api call` (у триггера нет события API), `Sender email is not activated` (отправитель не подтверждён), `Trigger not active` (триггер отключён), `Not in condition for` (подписчик не проходит условия). **Ответы:** `200` Успешная отправка Пример ответа `200`: ```json { "status": 1, "updated_variables": [], "status_text": "Success. Complete on 0.453127 sec.", "result": 191015674 } ``` #### Статистика триггера `GET https://mailganer.com/api/v2/triggers/{trigger_id}/stat/` · operationId: `getTriggerStats` Возвращает статистику по триггеру: суммарную или в разрезе дней за период. **Эндпоинт:** `GET https://mailganer.com/api/v2/triggers/:trigger_id/stat/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` ##### Path-параметры | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `trigger_id` | int | Да | ID триггера | ##### Query-параметры | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `start_date` | string | Нет | Дата начала в формате `YYYY-MM-DD` | | `end_date` | string | Нет | Дата конца в формате `YYYY-MM-DD` | ##### Пример curl ```bash curl --location 'https://mailganer.com/api/v2/triggers/1111/stat/?start_date=2022-08-01&end_date=2023-08-03' \ --header 'Authorization: CodeRequest {{api_key}}' ``` ##### Примечания - Без параметров дат — возвращается суммарная статистика по триггеру (объект `summary`). - Если передан только один из параметров (`start_date` или `end_date`) — также возвращается суммарная статистика. - Если переданы оба параметра — данные за указанный период (включая последний день) в разрезе дней плюс блок `summary`. - Поля статистики: `delivered` (доставлено), `clicked` (клики), `opened` (открытия), `not_available` (недоступно), `unsubscribed` (отписки), `spammed` (жалобы на спам), `sent` (отправлено). **Ответы:** `200` С датой, `401` Ошибка авторизации, `404` Триггер не найден Пример ответа `200`: ```json { "2023-08-01": { "delivered": 338, "clicked": 13, "opened": 60, "not_available": 4, "unsubscribed": 1, "spammed": 0, "sent": 344 }, "2023-08-02": { "delivered": 315, "clicked": 12, "opened": 54, "not_available": 0, "unsubscribed": 2, "spammed": 0, "sent": 316 }, "2023-08-03": { "delivered": 369, "clicked": 13, "opened": 57, "not_available": 0, "unsubscribed": 0, "spammed": 0, "sent": 369 }, "summary": { "delivered": 1022, "clicked": 38, "opened": 171, "not_available": 4, "unsubscribed": 3, "spammed": 0, "sent": 1029 } } ``` #### Получение статистики по отправке триггера `POST https://mailganer.com/api/v1/trigger/id_stat/` · operationId: `getTriggerSendStats` Возвращает статусы доставки по списку ID отправок триггера (пакетно). **Эндпоинт:** `POST https://mailganer.com/api/v1/trigger/id_stat/` **Авторизация:** без авторизации (noauth); API-ключ передаётся в теле запроса в поле `api_key` **Content-Type:** `application/json` ##### Тело запроса | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `api_key` | string | Да | API-ключ (см. https://mailganer.com/app/profile/settings/api/) | | `id_list` | array | Да | Список ID отправок для пакетного получения статусов | ##### Пример curl ```bash curl --location 'https://mailganer.com/api/v1/trigger/id_stat/' \ --header 'Content-Type: application/json' \ --data '{ "api_key": "{{api_key}}", "id_list": [123, 456] }' ``` ##### Примечания - Максимум **100 ID** в одном запросе. - Ответ: `status` (1 — успех, -1 — ошибка), `status_text` (`success`, `error` или `throttling`), `result` (массив статусов), `error` (описание ошибки, если есть). - Элемент `result`: `id` (ID отправки), `status` — одно из: `Доставлено`, `Не доставлено`, `Открыл`, `Кликнул`, `Пользователь считает спамом`. **Ответы:** `200` Успех Пример ответа `200`: ```json { "status": 1, "status_text": "success", "result": [ { "id": "123", "status": "Доставлено" }, { "id": "456", "status": "Не доставлено" } ] } ``` #### Получить список триггеров `GET https://mailganer.com/api/v2/triggers/` · operationId: `listTriggers` Возвращает список триггеров аккаунта (с пагинацией). **Эндпоинт:** `GET https://mailganer.com/api/v2/triggers/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` ##### Пример curl ```bash curl --location 'https://mailganer.com/api/v2/triggers/' \ --header 'Authorization: CodeRequest {{api_key}}' ``` ##### Примечания - Ответ постраничный: `count` (количество триггеров), `next` (ссылка на следующую страницу), `previous` (ссылка на предыдущую страницу), `results` (массив триггеров). - Элемент `results`: `id` (идентификатор триггера), `name` (название, может быть `null`), `sites` (списки, с которыми связан триггер). **Ответы:** `200` Список триггеров Пример ответа `200`: ```json { "count": 2, "next": null, "previous": null, "results": [ { "id": 1, "name": "Тестовый триггер", "sites": [ 32424, 1234, 13231 ] }, { "id": 4, "name": null, "sites": [ 9199 ] } ] } ``` #### Получить информацию о триггере `GET https://mailganer.com/api/v2/triggers/{trigger_id}/meta/` · operationId: `getTriggerMeta` Возвращает подробную информацию (метаданные) о триггере. **Эндпоинт:** `GET https://mailganer.com/api/v2/triggers/:trigger_id/meta/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` ##### Path-параметры | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `trigger_id` | int | Да | ID триггера | ##### Пример curl ```bash curl --location 'https://mailganer.com/api/v2/triggers/1111/meta/' \ --header 'Authorization: CodeRequest {{api_key}}' ``` ##### Примечания - Возвращаемые поля: `name` (название, ≤250), `group` (группа, ≤250), `topic` (тема письма), `sites` (ID связанных списков), `sites_names` (названия списков), `event` (тип события, ≤100), `sender_name` (≤255), `sender_email` (≤255), `utm_campaign` / `utm_source` / `utm_medium` (≤150), `user_utms` (пользовательские UTM, ≤255), `webversion` (ссылка на веб-версию, ≤255), `html_code` (HTML-контент письма), `created` (дата создания, `DD.MM.YYYY HH:MM`), `first_letter_date` (дата первой отправки), `last_activate_date` (дата последней активации), `type` (канал: Email, SMS, Viber), `active` (статус активности True/False). **Ответы:** `200` Успешный ответ, `401` Ошибка авторизации Пример ответа `200`: ```json { "name": "Trigger 1", "group": null, "topic": "Спасибо, что подписались на нас", "sites": [ 12345 ], "sites_names": [ "mailganer.com" ], "event": "Подписчик подтвердил подписку", "sender_name": "Mailganer", "sender_email": "info@mailganer.com", "utm_campaign": "", "utm_source": "", "utm_medium": "", "user_utms": "custom_utm1=value1&custom_utm2=value2", "webversion": "https://mailganer.com/app/trigger/webversion/XXXXXXXXXXX/", "html_code": "" } ``` #### Создание триггера `POST https://mailganer.com/api/v2/triggers/create/` · operationId: `createTrigger` Создаёт новый триггер в аккаунте. **Эндпоинт:** `POST https://mailganer.com/api/v2/triggers/create/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` ##### Тело запроса | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `name` | string | Да* | Название триггера (≤250 символов) | | `theme` | string | Нет | Тема письма триггера (≤250 символов) | | `sites` | array | Нет | Список ID списков (сегментов) | | `html-content` | string | Нет | HTML-вёрстка письма триггера | | `zip-content` | string | Нет | Ссылка на архив с вёрсткой (.zip) | \* В старой документации поле было необязательным, но без `name` API возвращает ошибку `400` «Это поле обязательно». ##### Пример curl ```bash curl --location 'https://mailganer.com/api/v2/triggers/create/' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data '{ "name": "Новый триггер", "theme": "Новый триггер", "sites": [94321], "html-content": "

Привет, это пример HTML-содержимого письма.

", "zip-content": "" }' ``` ##### Примечания - При использовании `html-content` спецсимволы экранируются: `&`→`%26`, `"`→`%22`, `\`→`%27`, `<`→`%3C`, `>`→`%3E`. - Ответ: `status` (`1`/`success` или `invalid`), `status_text` (`success`/`invalid`), `trigger_id` (ID созданного триггера), `step1_url` (ссылка на страницу редактирования), `error` (объект с ошибками при `invalid`). - Возможные ошибки: неверный API-ключ; недопустимый HTTP-метод; неверная ссылка `zip-content`; архив недоступен; формат не `.zip`; превышен размер архива; в архиве нет HTML-шаблона; неподтверждённый адрес отправителя; несуществующий ID сегмента; превышение длины `name` (250) или `theme` (250). **Ответы:** `200` Успешное создание, `400` Ошибка валидации Пример ответа `200`: ```json { "status": 1, "step1_url": "https://mailganer.com/app/trigger/step1/53223/", "status_text": "success", "trigger_id": 16434 } ``` #### История имейлов по триггеру `GET https://mailganer.com/api/v2/triggers/{trigger_id}/emails/` · operationId: `listTriggerEmails` Возвращает историю отправленных имейлов по триггеру (с пагинацией). **Эндпоинт:** `GET https://mailganer.com/api/v2/triggers/:trigger_id/emails/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` ##### Path-параметры | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `trigger_id` | int | Да | ID триггера | ##### Query-параметры | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `start_date` | string | Нет | Дата начала в формате `YYYY-MM-DD` | | `end_date` | string | Нет | Дата конца в формате `YYYY-MM-DD` | ##### Пример curl ```bash curl --location 'https://mailganer.com/api/v2/triggers/1111/emails/?start_date=2024-08-01&end_date=2024-08-03' \ --header 'Authorization: CodeRequest {{api_key}}' ``` ##### Примечания - Без параметров дат — возвращаются все имейлы за всю историю. - Если передан только один из параметров дат — фильтр игнорируется, возвращаются все имейлы. - Оба параметра (`start_date` и `end_date`) должны передаваться вместе для фильтрации по периоду. - Ответ постраничный: `count` (всего имейлов), `next` (ссылка на следующую страницу), `previous` (ссылка на предыдущую страницу), `results` (массив имейлов). - Элемент `results`: `id` (ID отправки), `queue_date` (время постановки в очередь), `sended` (время отправки, `null` если не отправлено), `email` (имейл подписчика), `email_id` (идентификатор имейла), `mg_hash` (уникальный хэш подписчика), `source_id` (ID списка), `status` (0 — в очереди, 1 — отправлено, 2 — доставлено, -1 — отменено, -2 — не доставлено, -3 — отписался), `action` (действие: Не открыл / Открыл / Кликнул / Отписался). **Ответы:** `200` История имейлов Пример ответа `200`: ```json { "count": 562458, "next": "https://mailganer.com/api/v2/triggers/1111/emails/?end_date=2024-08-30&page=2&start_date=2024-08-01", "previous": null, "results": [ { "id": 213250918, "queue_date": "2024-08-30T10:21:48.397765", "sended": null, "email": "example1@mail.com", "email_id": "1234567890", "mg_hash": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX", "source_id": "12345", "status": 0, "action": "Не открыл" } ] } ``` ### Товарные рекомендации Передача заказов и RFM-сегментов для товарных рекомендаций #### Передача оформленных заказов `POST https://mailganer.com/api/v1/recomend/orders/` · operationId: `createRecommendationOrders` Передаёт оформленные заказы в Mailganer для запуска триггеров с товарными рекомендациями. **Эндпоинт:** `POST https://mailganer.com/api/v1/recomend/orders/` **Авторизация:** без заголовка (noauth) — `api_key` передаётся в теле запроса (v1) **Content-Type:** `application/json` | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `api_key` | string | да | API-ключ (из настроек профиля) | | `source_id` | int | да | ID списка | | `orders` | array | да | Данные о заказах | | `orders[].id` | string | — | Номер заказа | | `orders[].status` | string | — | Статус заказа (например, «Новый») | | `orders[].channel` | string | — | Канал заказа (website / app / callcenter / offline) | | `orders[].date` | string | — | Дата заказа, Unix-timestamp | | `orders[].email` | string | — | Имейл покупателя | | `orders[].value.total` | float | — | Сумма заказа | | `orders[].items` | array | — | Товары заказа | | `orders[].items[].id` | int | — | ID товара | | `orders[].items[].price` | float | — | Цена товара | | `orders[].items[].quantity` | float | — | Количество | | `orders[].items[].categories` | array | — | ID категорий товара | ##### Поля ответа | Поле | Тип | Описание | |---|---|---| | `status` | int | `1` — триггер отправлен, `-1` — ошибка | | `status_text` | string | `success` или `error` | | `error` | string | Описание ошибки (при наличии) | ##### Пример curl ```bash curl --location --request POST 'https://mailganer.com/api/v1/recomend/orders/' \ --header 'Content-Type: application/json' \ --data-raw '{ "api_key": "XXX", "source_id": "50883", "orders": [ { "id": "12345", "status": "Новый", "channel": "domain.com", "date": "1619155834", "email": "email@domain.com", "value": { "total": 0.0 }, "items": [ { "id": 0, "price": 0.0, "quantity": 0.0, "categories": [1, 2, 3] } ] } ] }' ``` ##### Примечания - Метод **v1**: авторизация не через заголовок — `api_key` передаётся в теле запроса. - Ответ: `status` = `1` (триггер отправлен) или `-1` (ошибка); `status_text` = `success` / `error`; при ошибке добавляется поле `error`. - Вёрстка письма-триггера с блоком рекомендаций описана в отдельной инструкции (см. «Триггеры с товарными рекомендациями»). **Ответы:** `200` Success — триггер отправлен Пример ответа `200`: ```json { "status": 1, "status_text": "success" } ``` #### Триггеры с товарными рекомендациями `GET https://mailganer.com/documentation/recomend-layout-guide` · operationId: `getRecommendationLayoutGuide` (статья, не HTTP-метод: вызывать не нужно) Инструкция по подготовке вёрстки письма-триггера с блоком товарных рекомендаций. **Эндпоинт:** отдельного HTTP-эндпоинта у этой страницы нет — это руководство по вёрстке. Данные о заказах/покупках передаются методами «Передача оформленных заказов» (`POST https://mailganer.com/api/v1/recomend/orders/`) и «Передача RFM-сегмента» (`POST https://mailganer.com/api/v2/recomend/orders/`); данная страница описывает, как сверстать HTML-шаблон, в который движок подставит товары. URL запроса указывает на саму страницу документации. **Авторизация:** — ##### Переменные товара (`product`) | Переменная | Описание | |---|---| | `{{ product.id }}` | ID товара | | `{{ product.name }}` | Название | | `{{ product.description }}` | Описание | | `{{ product.barcode }}` | Штрихкод | | `{{ product.price }}` | Цена (формат «10 500») | | `{{ product.oldprice }}` | Старая цена (до скидки) | | `{{ product.currency }}` | Валюта | | `{{ product.url }}` | Ссылка на товар | | `{{ product.image_url }}` | Ссылка на изображение | | `{{ product.brand }}` | Бренд | | `{{ product.amount }}` | Количество | ##### Массивы и служебные переменные цикла | Переменная | Описание | |---|---| | `s_products` | Товары-источники (причина рекомендации, например из корзины / просмотренные) | | `r_products` | Рекомендованные товары | | `{{ forloop.first }}` | Первая итерация цикла | | `{{ forloop.last }}` | Последняя итерация цикла | | `{{ forloop.counter }}` | Номер текущей итерации | ##### Пример вёрстки ```html ...

Товары в корзине

{% for product in s_products %}

{{ product.name }}, {{ product.amount }} шт., {{ product.price }} руб.

{% endfor %}

Рекомендуем посмотреть

{% for product in r_products %}

{{ product.name }}, {{ product.price }} руб.

{% endfor %} ... ``` ##### Примечания - **Важно:** не вставляйте операторы `{% for %}` или `{% if %}` между тегами `` и `
` — иначе операторы автоматически переносятся перед `` и вёрстка ломается. - Нужны два цикла: один — по товарам-причинам рекомендации (`s_products`), второй — по рекомендованным товарам (`r_products`). - Условный вывод (например, старой цены) — через `{% if product.oldprice %}...{% endif %}`. #### Передача RFM-сегмента `POST https://mailganer.com/api/v2/recomend/orders/` · operationId: `createRecommendationRfmSegment` Передаёт данные о покупках для расчёта RFM-сегмента подписчиков. **Эндпоинт:** `POST https://mailganer.com/api/v2/recomend/orders/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `source_id` | int | да | ID списка | | `orders` | array | да | Данные о заказах | | `orders[].product_id` | string | да | Номер заказа | | `orders[].date` | date | да | Дата покупки (формат `ДД.ММ.ГГГГ`) | | `orders[].email` | string | да | Имейл покупателя | | `orders[].amount` | int | да | Стоимость покупки | ##### Пример curl ```bash curl --location --request POST 'https://mailganer.com/api/v2/recomend/orders/' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "source_id": "9345100", "orders": [ { "product_id": "35463453", "date": "01.03.2024", "email": "test@gmail.com", "amount": 4564 } ] }' ``` ##### Примечания - Метод **v2**: авторизация через заголовок `Authorization: CodeRequest {{api_key}}`. - `api_key` в теле запроса **не передаётся** (в отличие от v1-метода «Передача оформленных заказов»). **Ответы:** `400` Не переданы заказы, `401` Ключ API не передан или неверен, `2XX` Данные о заказах приняты ### Пользователи Управление пользователями аккаунта и балансом #### Получить список пользователей `GET https://mailganer.com/api/v2/users/` · operationId: `listUsers` Возвращает список пользователей. **Эндпоинт:** `GET https://mailganer.com/api/v2/users/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` ##### Пример curl ```bash curl --location --request GET 'https://mailganer.com/api/v2/users/' \ --header 'Authorization: CodeRequest {{api_key}}' ``` **Ответы:** `200` Список пользователей, `401` Ключ API не передан или неверен Пример ответа `200`: ```json { "count": 1, "next": null, "previous": null, "results": [ { "id": 21614, "username": "client@example.com", "avatar": "https://secure.gravatar.com/avatar/00000000000000000000000000000000.jpg", "fullname": "Иван Петров", "email": "client@example.com", "phone": "79123456789", "code_request": "ваш_ключ_api", "autologin": "код_автологина", "is_access_api_doi": false, "balance": "0.0", "smtp_api_keys": [] } ] } ``` #### Создать пользователя `POST https://mailganer.com/api/v2/users/` · operationId: `createUser` Создаёт нового пользователя (личный кабинет) в системе Mailganer. **Эндпоинт:** `POST https://mailganer.com/api/v2/users/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` ##### Параметры запроса | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `first_name` | string | да | Имя пользователя | | `email` | string | да | Имейл пользователя | | `phone` | string | нет | Телефон | ##### Параметры ответа | Поле | Тип | Описание | |---|---|---| | `id` | integer | ID пользователя | | `username` | string | Логин для авторизации | | `fullname` | string | Полное имя пользователя | | `email` | string | Имейл | | `phone` | string | Телефон | | `code_request` | string | Токен доступа к API | | `autologin` | string | Код автологина (авторизация на сайте) | ##### Пример curl ```bash curl --location --request POST 'https://mailganer.com/api/v2/users/' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "first_name": "Федор", "email": "test@example.com", "phone": "+79123456789" }' ``` ##### Примечания - Данная группа методов по умолчанию отключена. Для получения доступа обратитесь на api@mailganer.com. **Ответы:** `401` Ключ API не передан или неверен, `403` Группа методов не включена для аккаунта, `2XX` Пользователь создан #### Получить ссылку на пополнение баланса `POST https://mailganer.com/api/v2/pay/` · operationId: `createPaymentLink` Возвращает ссылку на оплату для пополнения баланса пользователя. **Эндпоинт:** `POST https://mailganer.com/api/v2/pay/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` ##### Параметры запроса | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `id` | integer | да | ID пользователя | | `summ` | integer | да | Сумма пополнения | | `payment_type` | string | да | Тип оплаты: `card` или `invoice` | | `requisites` | array | нет | Реквизиты; обязателен при `payment_type=invoice` | ###### Поля объекта `requisites` (при `payment_type=invoice`) | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `inn` | string | да | ИНН | | `bic` | string | да | БИК | | `rs` | string | да | Расчётный счёт | | `kpp` | string | да | КПП | | `name_org` | string | да | Название организации | | `address_org` | string | да | Адрес организации | ##### Параметры ответа | Поле | Тип | Описание | |---|---|---| | `url` | string | Ссылка на оплату | ##### Пример curl ```bash curl --location --request POST 'https://mailganer.com/api/v2/pay/' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "id": 12345, "summ": 1000, "payment_type": "card" }' ``` ##### Примечания - Данная группа методов по умолчанию отключена. Для получения доступа обратитесь на api@mailganer.com. - Для оплаты по счёту (`payment_type=invoice`) необходимо передать массив `requisites` со всеми полями реквизитов. **Ответы:** `default` Оплата по счету Пример ответа `default`: ```json { "url": "https://mailganer.com/app/finance/invoices/print/hash" } ``` #### Получить информацию о пользователе `GET https://mailganer.com/api/v2/users/{id}/` · operationId: `getUser` Возвращает информацию о пользователе по его ID. **Эндпоинт:** `GET https://mailganer.com/api/v2/users/:id/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` ##### Path-параметры | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `id` | integer | да | ID пользователя | ##### Пример curl ```bash curl --location --request GET 'https://mailganer.com/api/v2/users/:id/' \ --header 'Authorization: CodeRequest {{api_key}}' ``` **Ответы:** `200` Пользователь, `401` Ключ API не передан или неверен Пример ответа `200`: ```json { "id": 21614, "username": "client@example.com", "avatar": "https://secure.gravatar.com/avatar/00000000000000000000000000000000.jpg", "fullname": "Иван Петров", "email": "client@example.com", "phone": "79123456789", "code_request": "ваш_ключ_api", "autologin": "код_автологина", "is_access_api_doi": false, "balance": "0.0", "smtp_api_keys": [] } ``` #### Изменить пользователя `PATCH https://mailganer.com/api/v2/users/{id}/` · operationId: `updateUser` Изменяет параметры пользователя по его ID. **Эндпоинт:** `PATCH https://mailganer.com/api/v2/users/:id/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` ##### Path-параметры | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `id` | integer | да | ID пользователя | ##### Параметры запроса | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `is_access_api_doi` | boolean | нет | Флаг доступа к API DOI (поле присутствует в запросе) | ##### Пример curl ```bash curl --location --request PATCH 'https://mailganer.com/api/v2/users/:id/' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "is_access_api_doi": true }' ``` **Ответы:** `401` Ключ API не передан или неверен, `2XX` Пользователь обновлён #### Получение токена другого пользователя `POST https://mailganer.com/api/auth/` · operationId: `getUserToken` Возвращает API-токен и ID пользователя по логину и паролю (получение токена другого пользователя). **Эндпоинт:** `POST https://mailganer.com/api/auth/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` ##### Параметры запроса | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `username` | string (email) | да | Логин (имейл) | | `password` | string | да | Пароль | ##### Параметры ответа | Поле | Тип | Описание | |---|---|---| | `api_key` | string | Токен доступа к API | | `id` | integer | ID пользователя | ##### Пример curl ```bash curl --location --request POST 'https://mailganer.com/api/auth/' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "username": "test@mailganer.com", "password": "cb61c634" }' ``` ##### Примечания - Данная группа методов по умолчанию отключена. Для получения доступа обратитесь на api@mailganer.com. - Метод доступен по двум адресам: `POST https://mailganer.com/api/auth/` и `POST https://mailganer.com/api/v2/auth/`. **Ответы:** `400` Не переданы обязательные поля, `401` Ключ API не передан или неверен, `2XX` Токен пользователя #### Получить баланс `GET https://mailganer.com/api/v2/users/get_balance/` · operationId: `getUserBalance` Возвращает баланс личного кабинета Mailganer. **Эндпоинт:** `GET https://mailganer.com/api/v2/users/get_balance/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` ##### Параметры запроса | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `api_key` | string | да | API-ключ от личного кабинета Mailganer | ##### Параметры ответа | Поле | Тип | Описание | |---|---|---| | `balance` | integer | Баланс личного кабинета | ##### Пример curl ```bash curl --location --request GET 'https://mailganer.com/api/v2/users/get_balance/' \ --header 'Authorization: CodeRequest 54654768d9897654456wergdd5' \ --form 'api_key="54654768d9897654456wergdd5"' ``` ##### Примечания - Данная группа методов по умолчанию отключена. Для получения доступа обратитесь на api@mailganer.com. **Ответы:** `200` Success Пример ответа `200`: ```json { "balance": 3457 } ``` ### Шаблоны Получение HTML-вёрстки шаблонов #### Создание шаблона `POST https://mailganer.com/api/v2/template/` · operationId: `createTemplate` Создаёт HTML-шаблон письма в разделе «Шаблоны» личного кабинета. Вёрстка передаётся текстом, шаблон сразу доступен для редактирования в личном кабинете и для выбора при создании рассылки. **Эндпоинт:** `POST https://mailganer.com/api/v2/template/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` ##### Параметры тела | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `name` | Строка | ✅ | Название шаблона, не больше 250 символов | | `html` | Строка | ✅ | HTML-вёрстка письма. Размер не больше максимального размера письма для аккаунта, по умолчанию 2048 Кб | | `group_id` | Число | — | ID группы шаблонов. Если не передан, шаблон создаётся без группы | ##### Пример curl ```bash curl --location 'https://mailganer.com/api/v2/template/' \ --header 'Content-Type: application/json' \ --header 'Authorization: CodeRequest {{api_key}}' \ --data-raw '{ "name": "Письмо о доставке", "html": "
Здравствуйте, {{ name }}!
Отписаться", "group_id": 641 }' ``` ##### Примечания - В ответе возвращается `template_id`. Его можно передать в метод создания рассылки в параметре `template_id`. - `edit_url` — ссылка на редактирование шаблона в личном кабинете. - Лимит: не больше 60 запросов в час на аккаунт. - Возможные ошибки: - `400 Bad Request` — не передано обязательное поле (`status: invalid`, в `error` перечислены поля). - `401 Unauthorized` — не предоставлен или неверный ключ API. **Ответы:** `200` Шаблон создан, `400` Не переданы обязательные поля Пример ответа `200`: ```json { "template_id": "3e28f835-b2e6-43f1-9e82-f263a4a4a4fb", "edit_url": "https://mailganer.com/app/custom-template/3e28f835-b2e6-43f1-9e82-f263a4a4a4fb/" } ``` #### Получение HTML-вёрстки шаблона `GET https://mailganer.com/api/v2/template/{template_id}/` · operationId: `getTemplate` Возвращает HTML-вёрстку шаблона по его ID. **Эндпоинт:** `GET https://mailganer.com/api/v2/template/:template_id/` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` ##### Параметры пути | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `template_id` | Строка (UID) | — | ID шаблона. Оставьте пустым, чтобы получить ID и названия всех шаблонов | ##### Пример curl ```bash curl --location 'https://mailganer.com/api/v2/template/4f848a39-136b-42e7-9ba8-e4b4a9dadbe2/' \ --header 'Authorization: CodeRequest {{api_key}}' ``` ##### Примечания - ID шаблона можно взять из URL при просмотре шаблона в разделе «Шаблоны» (https://mailganer.com/app/custom-templates/). Пример URL: `https://mailganer.com/app/custom-template/4f848a39-136b-42e7-9ba8-e4b4a9dadbe2/`, где `4f848a39-136b-42e7-9ba8-e4b4a9dadbe2` — искомый UID шаблона. - Успешный ответ (200) содержит поле `text` с HTML-вёрсткой шаблона. - Возможные ошибки: - `401 Unauthorized` — не предоставлен или неверный ключ API от личного кабинета. - `403 Forbidden` — у пользователя нет доступа к запрашиваемому шаблону. - `404 Not Found` — шаблон с указанным ID не найден. **Ответы:** `200` Успех (200) Пример ответа `200`: ```json { "text": "..." } ``` ### Отчёты Формирование, статус и скачивание отчётов #### Создать задачу на формирование отчёта `POST https://mailganer.com/api/v2/tasks/emails_report` · operationId: `createReportTask` Запускает асинхронную задачу на формирование файла с данными аккаунта (выгрузка списка/сегмента или отчёт по рассылке). **Эндпоинт:** `POST https://mailganer.com/api/v2/tasks/emails_report` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` **Content-Type:** `application/json` ##### Параметры тела | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `file_type` | string | Да | Формат файла: `csv` или `xlsx` | | `site_id` | int | Нет* | ID списка — выгрузить всех подписчиков списка | | `segment_id` | int | Нет* | ID сегмента — выгрузить подписчиков сегмента | | `mailing_id` | int | Нет* | ID рассылки (требует `mailing_report_type`) | | `mailing_report_type` | string | Нет | Тип отчёта по рассылке: `general_mailing_report` — общий отчёт, `clicks` — отчёт по кликам | | `start_date` | string | Нет | Фильтр по дате от (дата создания подписчика), формат `YYYY-MM-DD` | | `end_date` | string | Нет | Фильтр по дате до (дата создания подписчика), формат `YYYY-MM-DD` | \* Нужно передать ровно **одну** группу: `site_id`, `segment_id` или `mailing_id`. ##### Пример curl ```bash curl --location --request POST 'https://mailganer.com/api/v2/tasks/emails_report' \ --header 'Authorization: CodeRequest {{api_key}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "mailing_id": 177022020521, "mailing_report_type": "general_mailing_report", "file_type": "csv" }' ``` ##### Примечания - Метод запускает асинхронную задачу; в ответе возвращается `task_id`, `state` и `task_type`. - Параметры `site_id`, `segment_id` и `mailing_id` взаимоисключающие — их нельзя комбинировать (иначе ошибка `Request cannot contain parameters from different report types...`). - Для `mailing_id` обязателен `mailing_report_type` (иначе `mailing_id is required for mailing_report_type parameter`). - Фильтры по датам (`start_date`/`end_date`) применяются к дате создания подписчика; для отчётов по рассылке игнорируются. - Для использования метода в аккаунте должно быть включено ограничение доступа к API по IP-адресам (иначе `403`). - **Порядок работы с отчётами:** 1) создать задачу этим методом → получить `task_id`; 2) опрашивать статус `GET /api/v2/tasks/:task_id`, пока `state` не станет `COMPLETED`; 3) скачать файл `GET /api/v2/tasks/:task_id/download_file`. **Ответы:** `200` Success — задача создана Пример ответа `200`: ```json { "task_id": "c8549c22-21f9-467b-9c74-870c34523432a048b", "state": "IN_PROGRESS", "task_type": "DOWNLOAD_MAILING_REPORT" } ``` #### Получение статуса задачи `GET https://mailganer.com/api/v2/tasks/{task_id}` · operationId: `getReportTask` Возвращает текущий статус задачи на формирование отчёта по её идентификатору. **Эндпоинт:** `GET https://mailganer.com/api/v2/tasks/:task_id` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` ##### Параметры пути | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `task_id` | string | Да | UUID задачи, полученный при её создании | ##### Пример curl ```bash curl --location --request GET 'https://mailganer.com/api/v2/tasks/:task_id' \ --header 'Authorization: CodeRequest {{api_key}}' ``` ##### Примечания - Поля ответа: `id` — UUID задачи; `state` — статус; `task_type` — тип отчёта (`DOWNLOAD_SITE_EMAILS`, `DOWNLOAD_SEGMENT`, `DOWNLOAD_MAILING_REPORT` и т.п.). - Значения `state`: `IN_PROGRESS` — выполняется; `COMPLETED` — успешно завершена, файл готов к скачиванию; `FAILED` — ошибка формирования. - Опрашивайте метод, пока `state` не станет `COMPLETED`, затем скачайте файл через `GET /api/v2/tasks/:task_id/download_file`. - Если задача не найдена — ответ с ошибкой `Task by id=... not found`. - Для использования метода в аккаунте должно быть включено ограничение доступа к API по IP-адресам (иначе `403`). **Ответы:** `200` Success — выполняется, `404` Error — задача не найдена Пример ответа `200`: ```json { "id": "a39929f4-dac8-4f5d-8d02-82c945623856", "state": "IN_PROGRESS", "task_type": "DOWNLOAD_MAILING_REPORT" } ``` #### Скачивание готового файла `GET https://mailganer.com/api/v2/tasks/{task_id}/download_file` · operationId: `downloadReportFile` Скачивает готовый файл отчёта по завершённой задаче. **Эндпоинт:** `GET https://mailganer.com/api/v2/tasks/:task_id/download_file` **Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}` ##### Параметры пути | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `task_id` | string | Да | UUID задачи, полученный при её создании | ##### Пример curl ```bash curl --location --request GET 'https://mailganer.com/api/v2/tasks/:task_id/download_file' \ --header 'Authorization: CodeRequest {{api_key}}' \ --output report.csv ``` ##### Примечания - Возвращает бинарный файл в формате, указанном при создании задачи (CSV или XLSX). - Скачивание доступно только после того, как задача перешла в статус `COMPLETED` (проверяйте через `GET /api/v2/tasks/:task_id`). - Если файл ещё не готов, метод вернёт ошибку `{"status": "error", "error": "Task has not file"}`. - Для использования метода в аккаунте должно быть включено ограничение доступа к API по IP-адресам (иначе `403`). - **Полный порядок:** создать задачу → дождаться статуса `COMPLETED` → скачать файл этим методом. **Ответы:** `400` Error — файл ещё не готов ### Постбек Передача конверсий на отдельном хосте постбека #### Передача конверсий и обновление переменной по ссылке `GET https://postback.mailganer.com/v1/` · operationId: `getPostbackConversion` Передача конверсий (postback). Источник: https://documentation.mailganer.com/reference/ Хост отдельный (postback.mailganer.com), авторизация не требуется (No Auth). Параметры передаются в query-строке. ##### Пример curl ```bash curl --location --request GET 'http://postback.mailganer.com/v1/?mailing_id={{public_id}}&sum=1000¤cy=RUB&offer=order&email_hash={{email_hash}}&goto_url=domain.com' ``` ##### Обновление переменной по ссылке Тот же адрес обновляет пользовательскую переменную подписчика по клику на ссылку в письме. Переменную передают как get-параметр `имя=значение` (в примере `nps=10`). `goto_url` должен содержать протокол и быть закодирован (urlencode). Авторизация не нужна. ```bash curl --location --request GET 'https://postback.mailganer.com/v1/?email_hash={{email_hash}}&mailing_id={{public_id}}&nps=10&goto_url=https%3A%2F%2Fdomain.com%2F%3Futm_source%3Dsource%26clickid%3D{{clickid}}' ``` **Ответы:** `400` Не переданы обязательные параметры, `2XX` Запрос принят