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

Библиотека для Python

Официальная библиотека для Python: mailganer на PyPI. Она подставляет ключ API, повторяет запрос при превышении лимита, обходит страницы и превращает ошибки API в понятные исключения. Python 3.8 и новее, без внешних зависимостей, лицензия MIT.

Установка​

pip install mailganer

Ключ API​

Ключ лежит в личном кабинете, раздел Ключ API. Передайте его в клиент или положите в переменную окружения MAILGANER_API_KEY. Вставляйте только сам ключ: заголовок Authorization: CodeRequest библиотека соберёт сама, а в v1-методах подставит ключ в тело запроса.

from mailganer import Mailganer

mg = Mailganer(api_key="ВАШ_API_КЛЮЧ")   # или Mailganer() с MAILGANER_API_KEY
print(mg.users.balance())

Подписчики​

# добавить одного
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").

Рассылки и триггеры​

draft = mg.mailings.create(name="Акция", theme="Скидка 20%", segment_id=123456,
                           from_email="news@example.com", from_name="Магазин",
                           html_content="<html>...</html>")
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)

Отчёты​

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:

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: Лимиты и пагинация.

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. Имена полей совпадают со справочником методов. Если нужного метода нет, отправьте запрос напрямую:

mg.request("GET", "/api/v2/tags/")

Новые методы API появляются в библиотеке со следующей версией. Что изменилось, смотрите в истории версий на PyPI.