mailganer 0.1.0__py3-none-any.whl

mailganer/__init__.py

@@ -0,0 +1,28 @@
+"""Официальный клиент REST API Mailganer для Python.
+
+Документация API: https://documentation.mailganer.com/
+"""
+
+from ._version import __version__
+from .client import Mailganer
+from .errors import (
+    AuthenticationError, MailganerError, NotFoundError, PermissionDeniedError, RateLimitError, ServerError,
+    ValidationError,
+)
+from .resources import Variables, postback_url
+from .webhooks import parse_webhook
+
+__all__ = [
+    "__version__",
+    "Mailganer",
+    "MailganerError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+    "Variables",
+    "parse_webhook",
+    "postback_url",
+]

mailganer/_http.py

@@ -0,0 +1,186 @@
+"""HTTP-слой: запрос, разбор ответа, ошибки и повторы. Только стандартная библиотека Python."""
+
+import json
+import time
+import uuid
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from ._version import __version__
+from .errors import MailganerError, RateLimitError, error_for_status
+
+DEFAULT_BASE_URL = "https://mailganer.com"
+USER_AGENT = "mailganer-python/{}".format(__version__)
+
+# v1-методы и часть v2 сообщают об ошибке в теле, иногда с HTTP 200.
+_BODY_ERROR_STATUSES = ("error", "invalid", -1, "-1")
+_BODY_ERROR_TEXTS = ("error", "invalid", "throttling")
+
+
+def urllib_transport(method, url, headers, body, timeout):
+    """Транспорт по умолчанию. Возвращает (status, headers, raw_bytes).
+
+    Тело передаётся и в GET: так работает, например, проверка верификации домена.
+    """
+    req = urllib.request.Request(url, data=body, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return resp.status, dict(resp.headers), resp.read()
+    except urllib.error.HTTPError as e:
+        return e.code, dict(e.headers or {}), e.read() or b""
+
+
+def encode_multipart(fields):
+    """form-data для v1-метода создания рассылки. fields: dict строк."""
+    boundary = "mailganer-" + uuid.uuid4().hex
+    parts = []
+    for name, value in fields.items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            value = "true" if value else "false"
+        elif isinstance(value, (dict, list)):
+            value = json.dumps(value, ensure_ascii=False)
+        parts.append(
+            "--{b}\r\nContent-Disposition: form-data; name=\"{n}\"\r\n\r\n{v}\r\n".format(b=boundary, n=name, v=value)
+        )
+    parts.append("--{}--\r\n".format(boundary))
+    return "".join(parts).encode("utf-8"), "multipart/form-data; boundary=" + boundary
+
+
+def _parse(raw, content_type):
+    if raw is None:
+        return None
+    if "application/json" in (content_type or "") or raw[:1] in (b"{", b"["):
+        try:
+            return json.loads(raw.decode("utf-8"))
+        except ValueError:
+            pass
+    try:
+        return raw.decode("utf-8")
+    except UnicodeDecodeError:
+        return raw
+
+
+def _body_error(data):
+    if not isinstance(data, dict):
+        return False
+    return data.get("status") in _BODY_ERROR_STATUSES or data.get("status_text") in _BODY_ERROR_TEXTS
+
+
+def _message(data, status):
+    if isinstance(data, dict):
+        for key in ("error", "detail", "msg", "message", "status_text"):
+            val = data.get(key)
+            if isinstance(val, str) and val:
+                return val
+        err = data.get("error")
+        if isinstance(err, dict) and err:
+            return "; ".join("{}: {}".format(k, " ".join(map(str, v)) if isinstance(v, list) else v) for k, v in err.items())
+        if isinstance(err, (dict, list)):
+            return "Ошибка в полях запроса"
+    if isinstance(data, str) and data.strip() and len(data) < 300:
+        return data.strip()
+    if status == 401:
+        return "Ключ API не передан или неверен"
+    return "Ошибка API Mailganer"
+
+
+def _header(headers, name):
+    for k, v in (headers or {}).items():
+        if k.lower() == name.lower():
+            return v
+    return None
+
+
+class HttpClient:
+    def __init__(self, api_key, base_url=DEFAULT_BASE_URL, timeout=30, max_retries=2, transport=None, sleep=time.sleep):
+        self.api_key = (api_key or "").strip()
+        if self.api_key.lower().startswith("coderequest "):
+            self.api_key = self.api_key[len("coderequest "):].strip()
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.transport = transport or urllib_transport
+        self._sleep = sleep
+
+    def request(self, method, path, query=None, json_body=None, form=None, v1_key=False, auth=True, raw=False, base_url=None):
+        """Выполнить запрос и вернуть разобранный ответ.
+
+        path — путь (/api/v2/...) или полный URL (ссылки next в постраничных ответах).
+        v1_key — подставить api_key в тело (v1-методы). raw — вернуть байты (скачивание файла).
+        """
+        if auth and not self.api_key:
+            raise MailganerError("Нужен api_key: Mailganer(api_key=...). Ключ лежит в личном кабинете, раздел «Ключ API».")
+        url = path if path.startswith("http") else (base_url or self.base_url) + path
+        if query:
+            q = {k: _query_value(v) for k, v in query.items() if v is not None}
+            if q:
+                url += ("&" if "?" in url else "?") + urllib.parse.urlencode(q)
+
+        headers = {"Accept": "application/json", "User-Agent": USER_AGENT}
+        if auth and not v1_key:
+            headers["Authorization"] = "CodeRequest " + self.api_key
+        body = None
+        if form is not None:
+            fields = dict(form)
+            if v1_key:
+                fields["api_key"] = self.api_key
+            body, headers["Content-Type"] = encode_multipart(fields)
+        elif json_body is not None:
+            payload = json_body
+            if v1_key and isinstance(payload, dict):
+                payload = dict(payload, api_key=self.api_key)
+            body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+
+        attempt = 0
+        while True:
+            status, resp_headers, raw_body = self.transport(method, url, headers, body, self.timeout)
+            if raw and 200 <= status < 300:
+                return raw_body
+            data = _parse(raw_body, _header(resp_headers, "Content-Type"))
+            failed = status >= 400 or _body_error(data)
+            if not failed:
+                return data
+            throttled = status in (429, 503) or (isinstance(data, dict) and data.get("status_text") == "throttling")
+            if throttled and attempt < self.max_retries:
+                self._sleep(_retry_delay(resp_headers, attempt))
+                attempt += 1
+                continue
+            cls = RateLimitError if throttled and status < 500 else error_for_status(status if status >= 400 else 400)
+            raise cls(_message(data, status), status=status, body=data)
+
+    def paginate(self, path, query=None):
+        """Пройти все страницы постраничного ответа (count / next / results) и отдать элементы по одному."""
+        page = self.request("GET", path, query=query)
+        while True:
+            if isinstance(page, dict) and isinstance(page.get("results"), list):
+                for item in page["results"]:
+                    yield item
+                nxt = page.get("next")
+                if not nxt:
+                    return
+                page = self.request("GET", nxt)
+            else:
+                if isinstance(page, list):
+                    for item in page:
+                        yield item
+                return
+
+
+def _query_value(v):
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    return v
+
+
+def _retry_delay(headers, attempt):
+    after = _header(headers, "Retry-After")
+    try:
+        if after is not None:
+            return min(float(after), 60.0)
+    except ValueError:
+        pass
+    return min(2 ** attempt, 30)

mailganer/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

mailganer/client.py

@@ -0,0 +1,50 @@
+"""Клиент REST API Mailganer."""
+
+import os
+
+from ._http import DEFAULT_BASE_URL, HttpClient
+from .resources import (
+    Lists, Mailings, Postback, Recommendations, Reports, Segments, Subscribers, Tags, Templates, Triggers, Users,
+    Variables,
+)
+
+
+class Mailganer:
+    """Клиент REST API Mailganer.
+
+        from mailganer import Mailganer
+        mg = Mailganer(api_key="ваш_ключ")      # или переменная окружения MAILGANER_API_KEY
+        mg.subscribers.add("user@example.com", source=49767, name="Иван")
+
+    Ключ API лежит в личном кабинете, раздел «Ключ API»: https://mailganer.com/app/profile/settings/api/
+    Вставляйте только сам ключ: заголовок Authorization: CodeRequest <ключ> клиент соберёт сам,
+    а в v1-методах подставит ключ в тело запроса.
+
+    max_retries — сколько раз повторить запрос при 429/503 и throttling (с паузой);
+    transport — свой транспорт для тестов: callable(method, url, headers, body, timeout) -> (status, headers, bytes).
+    """
+
+    def __init__(self, api_key=None, base_url=DEFAULT_BASE_URL, timeout=30, max_retries=2, transport=None):
+        self._http = HttpClient(
+            api_key if api_key is not None else os.environ.get("MAILGANER_API_KEY", ""),
+            base_url=base_url, timeout=timeout, max_retries=max_retries, transport=transport,
+        )
+        self.subscribers = Subscribers(self._http)
+        self.lists = Lists(self._http)
+        self.segments = Segments(self._http)
+        self.variables = Variables(self._http)
+        self.mailings = Mailings(self._http)
+        self.triggers = Triggers(self._http)
+        self.recommendations = Recommendations(self._http)
+        self.users = Users(self._http)
+        self.tags = Tags(self._http)
+        self.templates = Templates(self._http)
+        self.reports = Reports(self._http)
+        self.postback = Postback(self._http)
+
+    def request(self, method, path, **kwargs):
+        """Произвольный запрос к API, если метода ещё нет в библиотеке: mg.request("GET", "/api/v2/tags/")."""
+        return self._http.request(method, path, **kwargs)
+
+    def __repr__(self):
+        return "<Mailganer {}>".format(self._http.base_url)

mailganer/errors.py

@@ -0,0 +1,70 @@
+"""Ошибки клиента Mailganer."""
+
+
+class MailganerError(Exception):
+    """Общая ошибка API Mailganer.
+
+    status — HTTP-код ответа (у v1-методов ошибка может прийти и с кодом 200),
+    body — разобранное тело ответа (dict, list или строка),
+    errors — ошибки по полям, если API их вернул: {"email": ["Это поле обязательно."]}.
+    """
+
+    def __init__(self, message, status=None, body=None):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.body = body
+        self.errors = _field_errors(body)
+
+    def __str__(self):
+        return "{} (HTTP {})".format(self.message, self.status) if self.status else self.message
+
+
+class AuthenticationError(MailganerError):
+    """401: ключ API не передан или неверен."""
+
+
+class PermissionDeniedError(MailganerError):
+    """403: метод не включён для аккаунта или нет доступа к объекту."""
+
+
+class NotFoundError(MailganerError):
+    """404: объект не найден."""
+
+
+class ValidationError(MailganerError):
+    """400: не прошли проверку поля запроса. Подробности по полям — в .errors."""
+
+
+class RateLimitError(MailganerError):
+    """429 или throttling: превышен лимит запросов. Клиент сам повторяет запрос, эта ошибка — если повторы кончились."""
+
+
+class ServerError(MailganerError):
+    """5xx: сервер временно не смог обработать запрос."""
+
+
+def _field_errors(body):
+    if isinstance(body, dict):
+        err = body.get("error")
+        if isinstance(err, dict):
+            return err
+        if isinstance(err, list):  # массовые методы: ошибка по каждой записи
+            return err
+    return {}
+
+
+def error_for_status(status):
+    if status == 400:
+        return ValidationError
+    if status == 401:
+        return AuthenticationError
+    if status == 403:
+        return PermissionDeniedError
+    if status == 404:
+        return NotFoundError
+    if status == 429:
+        return RateLimitError
+    if status and status >= 500:
+        return ServerError
+    return MailganerError

mailganer/resources.py

@@ -0,0 +1,441 @@
+"""Методы API по разделам документации. Имена полей — как в API, чтобы код совпадал со справочником:
+https://documentation.mailganer.com/reference/
+
+Необязательные поля передаются именованными аргументами (**fields) и уходят в запрос как есть.
+Поля с дефисом (html-content и т.п.) можно передать через подчёркивание: html_content.
+"""
+
+POSTBACK_BASE_URL = "https://postback.mailganer.com"
+
+
+def _clean(d):
+    """Убрать None, чтобы не затирать сохранённые значения пустыми."""
+    return {k: v for k, v in d.items() if v is not None}
+
+
+def _dash(fields, names):
+    """html_content -> html-content для полей, которые в API пишутся через дефис."""
+    out = {}
+    for k, v in fields.items():
+        key = k.replace("_", "-") if k in names else k
+        out[key] = v
+    return out
+
+
+def _require(**kwargs):
+    for name, value in kwargs.items():
+        if value is None or value == "" or value == []:
+            raise ValueError("Нужен параметр {}".format(name))
+
+
+class _Resource:
+    def __init__(self, http):
+        self._http = http
+
+
+class Subscribers(_Resource):
+    """Подписчики."""
+
+    def add(self, email, source, **fields):
+        """Добавить подписчика. source — ID списка, список ID или "all".
+
+        Поля: phone, name, surname, patronymic, gender, birthday, city, add_tag, delete_tag,
+        user_vars, not_doi, need_activate, add_category, delete_category.
+        """
+        _require(email=email, source=source)
+        return self._http.request("POST", "/api/v2/emails/", json_body=_clean(dict(fields, email=email, source=source)))
+
+    def add_many(self, subscribers):
+        """Массовое добавление, до 50 подписчиков за запрос. Если хотя бы одна запись с ошибкой, не добавится ни одна.
+
+        subscribers: список словарей с теми же полями, что у add().
+        """
+        _require(subscribers=subscribers)
+        if len(subscribers) > 50:
+            raise ValueError("Не больше 50 подписчиков за запрос, для больших пачек — add_many_v3()")
+        return self._http.request("POST", "/api/v2/emails/", json_body=list(subscribers))
+
+    def add_many_v3(self, subscribers):
+        """Массовое добавление v3 с подробным ответом по каждой записи.
+
+        Возвращает {"successful": [...], "failed": [...], "warnings": [...]}. Частичный успех (HTTP 207)
+        ошибкой не считается: смотрите failed и warnings. Лимит 2000 запросов в минуту.
+        """
+        _require(subscribers=subscribers)
+        return self._http.request("POST", "/api/v3/emails/", json_body=list(subscribers))
+
+    def list(self, email=None, source=None, start_date=None, end_date=None, updated_at_start=None,
+             updated_at_end=None, last_activity_days=None):
+        """Подписчики с фильтрами, одна страница (25 записей): {"count", "next", "previous", "results"}. Даты — YYYY-MM-DD."""
+        return self._http.request("GET", "/api/v2/emails/", query=locals_query(locals()))
+
+    def list_all(self, **filters):
+        """То же, что list(), но проходит все страницы и отдаёт подписчиков по одному."""
+        return self._http.paginate("/api/v2/emails/", query=_clean(filters))
+
+    def get(self, mg_hash):
+        """Подписчик по mg_hash."""
+        _require(mg_hash=mg_hash)
+        return self._http.request("GET", "/api/v2/emails/{}/".format(mg_hash))
+
+    def update(self, mg_hash, **fields):
+        """Обновить подписчика по mg_hash. Чтобы удалить переменную, передайте её в user_vars со значением None."""
+        _require(mg_hash=mg_hash)
+        return self._http.request("PATCH", "/api/v2/emails/{}/".format(mg_hash), json_body=dict(fields))
+
+    def update_by_email(self, email, source, **fields):
+        """Обновить подписчика по имейлу и списку."""
+        _require(email=email, source=source)
+        return self._http.request("PATCH", "/api/v2/emails/update/", json_body=dict(fields, email=email, source=source))
+
+    def update_many(self, subscribers):
+        """Массовое обновление: список словарей, в каждом email и source плюс меняемые поля."""
+        _require(subscribers=subscribers)
+        return self._http.request("PATCH", "/api/v2/emails/mass/", json_body=list(subscribers))
+
+    def unsubscribe(self, mg_hash):
+        """Отписать подписчика по mg_hash."""
+        _require(mg_hash=mg_hash)
+        return self._http.request("POST", "/api/v2/emails/{}/unsubscribe/".format(mg_hash))
+
+    def unsubscribe_by_email(self, email, source):
+        """Отписать подписчика по имейлу и списку."""
+        _require(email=email, source=source)
+        return self._http.request("POST", "/api/v2/emails/unsubscribe/", json_body={"email": email, "source": source})
+
+    def validate(self, email, source):
+        """Проверить имейл: в ответе is_valid и corrected_email."""
+        _require(email=email, source=source)
+        return self._http.request("POST", "/api/v2/emails/validate/", json_body={"email": email, "source": source})
+
+
+class Lists(_Resource):
+    """Списки."""
+
+    def create(self, domain):
+        """Создать список. domain — название списка."""
+        _require(domain=domain)
+        return self._http.request("POST", "/api/v2/sites/", json_body={"domain": domain})
+
+    def list(self, simple=None):
+        """Списки, одна страница. simple=True — только id и domain."""
+        return self._http.request("GET", "/api/v2/sites/", query=_clean({"simple": simple}))
+
+    def list_all(self, simple=None):
+        """Все списки, по одному."""
+        return self._http.paginate("/api/v2/sites/", query=_clean({"simple": simple}))
+
+    def verify_domain(self, domain):
+        """Статус верификации домена отправителя: verification_status, spf_status, dmarc_status, dkim_status.
+
+        API читает domain из тела GET-запроса, клиент передаёт его именно так.
+        """
+        _require(domain=domain)
+        return self._http.request("GET", "/api/v2/sites/verify_domain/", json_body={"domain": domain})
+
+    def set_webhook(self, list_id, url, is_active=None, is_use_auth_key=None, is_enable_retry=None):
+        """Задать URL вебхука для списка. События приходят на url, разобрать их поможет mailganer.parse_webhook()."""
+        _require(list_id=list_id, url=url)
+        body = _clean({"id": list_id, "url": url, "is_active": is_active,
+                       "is_use_auth_key": is_use_auth_key, "is_enable_retry": is_enable_retry})
+        return self._http.request("POST", "/api/v2/sites/set_webhook", json_body=body)
+
+
+class Segments(_Resource):
+    """Сегменты."""
+
+    def create(self, title, conditions):
+        """Создать сегмент. conditions: [{"condition": 6, "type_value": 4, "value": ["Тег"]}, ...]."""
+        _require(title=title, conditions=conditions)
+        return self._http.request("POST", "/api/v2/segments/", json_body={"title": title, "conditions": conditions})
+
+    def list(self):
+        """Сегменты, одна страница."""
+        return self._http.request("GET", "/api/v2/segments/")
+
+    def list_all(self):
+        """Все сегменты, по одному."""
+        return self._http.paginate("/api/v2/segments/")
+
+    def get(self, segment_id):
+        """Сегмент по ID."""
+        _require(segment_id=segment_id)
+        return self._http.request("GET", "/api/v2/segments/{}".format(segment_id))
+
+    def send_trigger(self, segment_id, trigger_id, ignore_trigger_conditions=None):
+        """Запустить триггер на сегмент. ignore_trigger_conditions=True — отправить сразу, без условий триггера."""
+        _require(segment_id=segment_id, trigger_id=trigger_id)
+        body = _clean({"trigger_id": trigger_id, "ignore_trigger_conditions": ignore_trigger_conditions})
+        return self._http.request("POST", "/api/v2/segments/{}/send_trigger/".format(segment_id), json_body=body)
+
+
+class Variables(_Resource):
+    """Пользовательские переменные."""
+
+    STRING, INTEGER, FLOAT, DATE, DATETIME, BOOLEAN, JSON = 0, 1, 2, 3, 4, 6, 8
+
+    def create(self, source, title, type, name=None):
+        """Создать переменную в списке source. type — Variables.STRING / INTEGER / FLOAT / DATE / DATETIME / BOOLEAN / JSON."""
+        _require(source=source, title=title, type=type)
+        return self._http.request("POST", "/api/v2/user_vars/",
+                                  json_body=_clean({"source": source, "title": title, "type": type, "name": name}))
+
+    def list(self, source=None):
+        """Переменные, одна страница. source — ID списка."""
+        return self._http.request("GET", "/api/v2/user_vars/", query=_clean({"source": source}))
+
+    def list_all(self, source=None):
+        """Все переменные, по одной."""
+        return self._http.paginate("/api/v2/user_vars/", query=_clean({"source": source}))
+
+
+class Mailings(_Resource):
+    """Рассылки."""
+
+    _DASHED = ("html_content", "amp_html_content", "zip_content", "amp_zip_content")
+
+    def create(self, **fields):
+        """Создать черновик рассылки (v1). Поля: name, theme, from_name, from_email, segment_id, html_content,
+        amp_html_content, template_id, zip_content, amp_zip_content, utm_campaign, utm_source, utm_medium,
+        user_utms (dict), variables (dict). Ключ API подставляется сам.
+        """
+        return self._http.request("POST", "/api/v1/mailing/create/", form=_dash(_clean(fields), self._DASHED), v1_key=True)
+
+    def send(self, public_id, datetime_send=None, is_chunked=None, chunk_size=None, chunk_timeout=None):
+        """Отправить рассылку. datetime_send — "DD.MM.YYYY HH:MM"; is_chunked — распределённая отправка."""
+        _require(public_id=public_id)
+        body = _clean({"public_id": public_id, "datetime_send": datetime_send, "is_chunked": is_chunked,
+                       "chunk_size": chunk_size, "chunk_timeout": chunk_timeout})
+        return self._http.request("POST", "/api/v2/mailing/send/", json_body=body)
+
+    def get(self, public_id):
+        """Рассылка по public_id."""
+        _require(public_id=public_id)
+        return self._http.request("GET", "/api/v2/mailing/{}".format(public_id))
+
+    def list(self, start_date=None, end_date=None):
+        """Рассылки, одна страница. Даты — YYYY-MM-DD."""
+        return self._http.request("GET", "/api/v2/mailing/", query=_clean({"start_date": start_date, "end_date": end_date}))
+
+    def list_all(self, start_date=None, end_date=None):
+        """Все рассылки, по одной."""
+        return self._http.paginate("/api/v2/mailing/", query=_clean({"start_date": start_date, "end_date": end_date}))
+
+    def stats(self, public_id, start_date=None, end_date=None):
+        """Статистика рассылки по дням и суммарно."""
+        _require(public_id=public_id)
+        return self._http.request("GET", "/api/v2/mailing/{}/stat/".format(public_id),
+                                  query=_clean({"start_date": start_date, "end_date": end_date}))
+
+
+class Triggers(_Resource):
+    """Триггеры."""
+
+    _DASHED = ("html_content", "zip_content")
+
+    def send(self, trigger_id, email, **fields):
+        """Отправить триггер подписчику. Поля: doi_ok, ignore_unsubscribed, ignore_spam, sender_name, sender_email,
+        variables (dict).
+        """
+        _require(trigger_id=trigger_id, email=email)
+        return self._http.request("POST", "/api/v2/triggers/{}/send/".format(trigger_id),
+                                  json_body=_clean(dict(fields, email=email)))
+
+    def stats(self, trigger_id, start_date=None, end_date=None):
+        """Статистика триггера: суммарно или по дням, если переданы обе даты."""
+        _require(trigger_id=trigger_id)
+        return self._http.request("GET", "/api/v2/triggers/{}/stat/".format(trigger_id),
+                                  query=_clean({"start_date": start_date, "end_date": end_date}))
+
+    def send_stats(self, id_list):
+        """Статусы доставки по ID отправок (v1), не больше 100 ID за запрос. Ключ API подставляется сам."""
+        _require(id_list=id_list)
+        if len(id_list) > 100:
+            raise ValueError("Не больше 100 ID за запрос")
+        return self._http.request("POST", "/api/v1/trigger/id_stat/", json_body={"id_list": list(id_list)}, v1_key=True)
+
+    def list(self):
+        """Триггеры, одна страница."""
+        return self._http.request("GET", "/api/v2/triggers/")
+
+    def list_all(self):
+        """Все триггеры, по одному."""
+        return self._http.paginate("/api/v2/triggers/")
+
+    def meta(self, trigger_id):
+        """Информация о триггере."""
+        _require(trigger_id=trigger_id)
+        return self._http.request("GET", "/api/v2/triggers/{}/meta/".format(trigger_id))
+
+    def create(self, name, **fields):
+        """Создать триггер. Поля: theme, sites (список ID списков), html_content, zip_content."""
+        _require(name=name)
+        return self._http.request("POST", "/api/v2/triggers/create/",
+                                  json_body=_dash(_clean(dict(fields, name=name)), self._DASHED))
+
+    def emails(self, trigger_id, start_date=None, end_date=None):
+        """История имейлов по триггеру, одна страница. Фильтр работает, только если переданы обе даты."""
+        _require(trigger_id=trigger_id)
+        return self._http.request("GET", "/api/v2/triggers/{}/emails/".format(trigger_id),
+                                  query=_clean({"start_date": start_date, "end_date": end_date}))
+
+    def emails_all(self, trigger_id, start_date=None, end_date=None):
+        """Вся история имейлов по триггеру, по одному."""
+        _require(trigger_id=trigger_id)
+        return self._http.paginate("/api/v2/triggers/{}/emails/".format(trigger_id),
+                                   query=_clean({"start_date": start_date, "end_date": end_date}))
+
+
+class Recommendations(_Resource):
+    """Товарные рекомендации."""
+
+    def send_orders(self, source_id, orders):
+        """Передать оформленные заказы (v1). Ключ API подставляется сам."""
+        _require(source_id=source_id, orders=orders)
+        return self._http.request("POST", "/api/v1/recomend/orders/",
+                                  json_body={"source_id": source_id, "orders": list(orders)}, v1_key=True)
+
+    def send_rfm_orders(self, source_id, orders):
+        """Передать покупки для RFM-сегмента: [{"product_id", "date" (ДД.ММ.ГГГГ), "email", "amount"}]."""
+        _require(source_id=source_id, orders=orders)
+        return self._http.request("POST", "/api/v2/recomend/orders/", json_body={"source_id": source_id, "orders": list(orders)})
+
+
+class Users(_Resource):
+    """Пользователи. Группа методов по умолчанию выключена, доступ — через api@mailganer.com (кроме balance())."""
+
+    def create(self, first_name, email, phone=None):
+        """Создать пользователя (личный кабинет)."""
+        _require(first_name=first_name, email=email)
+        return self._http.request("POST", "/api/v2/users/", json_body=_clean({"first_name": first_name, "email": email, "phone": phone}))
+
+    def list(self):
+        """Пользователи, одна страница."""
+        return self._http.request("GET", "/api/v2/users/")
+
+    def get(self, user_id):
+        """Пользователь по ID."""
+        _require(user_id=user_id)
+        return self._http.request("GET", "/api/v2/users/{}/".format(user_id))
+
+    def update(self, user_id, **fields):
+        """Изменить пользователя, например is_access_api_doi=True."""
+        _require(user_id=user_id)
+        return self._http.request("PATCH", "/api/v2/users/{}/".format(user_id), json_body=dict(fields))
+
+    def token(self, username, password):
+        """Токен (ключ API) другого пользователя по логину и паролю: {"api_key", "id"}."""
+        _require(username=username, password=password)
+        return self._http.request("POST", "/api/auth/", json_body={"username": username, "password": password})
+
+    def balance(self):
+        """Баланс аккаунта: {"balance": ...}."""
+        return self._http.request("GET", "/api/v2/users/get_balance/")
+
+    def payment_link(self, user_id, summ, payment_type, requisites=None):
+        """Ссылка на пополнение баланса. payment_type — "card" или "invoice" (тогда нужны requisites)."""
+        _require(user_id=user_id, summ=summ, payment_type=payment_type)
+        body = _clean({"id": user_id, "summ": summ, "payment_type": payment_type, "requisites": requisites})
+        return self._http.request("POST", "/api/v2/pay/", json_body=body)
+
+
+class Tags(_Resource):
+    """Теги (метки)."""
+
+    def create(self, name):
+        """Создать тег, не длиннее 140 символов."""
+        _require(name=name)
+        return self._http.request("POST", "/api/v2/tags/", json_body={"name": name})
+
+    def list(self):
+        """Теги, одна страница."""
+        return self._http.request("GET", "/api/v2/tags/")
+
+    def list_all(self):
+        """Все теги, по одному."""
+        return self._http.paginate("/api/v2/tags/")
+
+
+class Templates(_Resource):
+    """Шаблоны."""
+
+    def create(self, name, html, group_id=None):
+        """Создать HTML-шаблон: {"template_id", "edit_url"}. Лимит 60 запросов в час."""
+        _require(name=name, html=html)
+        return self._http.request("POST", "/api/v2/template/", json_body=_clean({"name": name, "html": html, "group_id": group_id}))
+
+    def get(self, template_id):
+        """HTML-вёрстка шаблона: {"text": "<!DOCTYPE html>..."}."""
+        _require(template_id=template_id)
+        return self._http.request("GET", "/api/v2/template/{}/".format(template_id))
+
+
+class Reports(_Resource):
+    """Отчёты: создать задачу, дождаться готовности, скачать файл."""
+
+    def create(self, file_type, site_id=None, segment_id=None, mailing_id=None, mailing_report_type=None,
+               start_date=None, end_date=None):
+        """Создать задачу на отчёт. Нужно ровно одно из: site_id, segment_id, mailing_id (с mailing_report_type:
+        "general_mailing_report" или "clicks"). file_type — "csv" или "xlsx".
+        """
+        _require(file_type=file_type)
+        if sum(x is not None for x in (site_id, segment_id, mailing_id)) != 1:
+            raise ValueError("Передайте ровно одно из: site_id, segment_id, mailing_id")
+        body = _clean({"file_type": file_type, "site_id": site_id, "segment_id": segment_id, "mailing_id": mailing_id,
+                       "mailing_report_type": mailing_report_type, "start_date": start_date, "end_date": end_date})
+        return self._http.request("POST", "/api/v2/tasks/emails_report", json_body=body)
+
+    def get(self, task_id):
+        """Статус задачи: state = IN_PROGRESS / COMPLETED / FAILED."""
+        _require(task_id=task_id)
+        return self._http.request("GET", "/api/v2/tasks/{}".format(task_id))
+
+    def download(self, task_id):
+        """Скачать готовый файл отчёта, вернуть байты. Требует ограничения доступа к API по IP в аккаунте."""
+        _require(task_id=task_id)
+        return self._http.request("GET", "/api/v2/tasks/{}/download_file".format(task_id), raw=True)
+
+    def wait(self, task_id, timeout=600, interval=5):
+        """Опрашивать задачу, пока не станет COMPLETED, и вернуть её. FAILED или таймаут — исключение."""
+        import time
+        from .errors import MailganerError
+
+        deadline = time.monotonic() + timeout
+        while True:
+            task = self.get(task_id)
+            state = (task or {}).get("state")
+            if state == "COMPLETED":
+                return task
+            if state == "FAILED":
+                raise MailganerError("Отчёт не сформирован (state=FAILED)", body=task)
+            if time.monotonic() >= deadline:
+                raise MailganerError("Отчёт не готов за {} с (state={})".format(timeout, state), body=task)
+            self._http._sleep(interval)
+
+
+class Postback(_Resource):
+    """Постбек: конверсии и обновление переменной по ссылке. Отдельный хост, без ключа API."""
+
+    def conversion(self, mailing_id, email_hash, sum=None, currency=None, offer=None, goto_url=None, **variables):
+        """Передать конверсию по рассылке. Дополнительные именованные аргументы уходят как переменные подписчика (nps=10)."""
+        _require(mailing_id=mailing_id, email_hash=email_hash)
+        query = _clean(dict(variables, mailing_id=mailing_id, email_hash=email_hash, sum=sum, currency=currency,
+                            offer=offer, goto_url=goto_url))
+        return self._http.request("GET", "/v1/", query=query, auth=False, base_url=POSTBACK_BASE_URL)
+
+
+def postback_url(goto_url=None, mailing_id="{{public_id}}", email_hash="{{email_hash}}", **params):
+    """Ссылка постбека для вставки в письмо. По умолчанию подставляет переменные письма {{public_id}} и
+    {{email_hash}}, их заменит Mailganer при отправке. Пример: postback_url("https://shop.ru/", nps=10).
+    """
+    import urllib.parse
+
+    query = dict(params, email_hash=email_hash, mailing_id=mailing_id)
+    if goto_url is not None:
+        query["goto_url"] = goto_url
+    qs = urllib.parse.urlencode(_clean(query), safe="{}")
+    return POSTBACK_BASE_URL + "/v1/?" + qs
+
+
+def locals_query(values):
+    return _clean({k: v for k, v in values.items() if k != "self"})

mailganer/webhooks.py

@@ -0,0 +1,68 @@
+"""Разбор входящих вебхуков Mailganer.
+
+Mailganer шлёт POST (application/x-www-form-urlencoded) на URL, заданный методом lists.set_webhook().
+Тип события — в поле type:
+    1 — изменение статуса подписчика,
+    2 — изменение данных подписчика,
+    3 — взаимодействие с письмом (доставлено, открыто, клик, отписка, жалоба, недоставка),
+    4 — срабатывание события в триггере.
+"""
+
+import json
+import urllib.parse
+
+EVENT_NAMES = {
+    1: "subscriber_status",
+    2: "subscriber_data",
+    3: "mail_interaction",
+    4: "trigger_event",
+}
+
+MAIL_ACTIONS = {
+    -3: "not_delivered",
+    -2: "spam_complaint",
+    -1: "unsubscribed",
+    1: "delivered",
+    2: "opened",
+    3: "clicked",
+}
+
+_INT_FIELDS = ("type", "action", "source", "source_id", "status", "src", "gender")
+
+
+def parse_webhook(body):
+    """Разобрать тело вебхука: bytes, str (как пришло) или dict (если фреймворк уже разобрал форму).
+
+    Возвращает dict с полями события, где числа приведены к int, плюс:
+        event — имя события (subscriber_status, subscriber_data, mail_interaction, trigger_event),
+        action_name — для mail_interaction: delivered / opened / clicked / unsubscribed / spam_complaint / not_delivered,
+        user_vars — для trigger_event: переменные подписчика без префикса user_var_.
+    """
+    if isinstance(body, (bytes, bytearray)):
+        body = body.decode("utf-8")
+    if isinstance(body, str):
+        pairs = urllib.parse.parse_qsl(body, keep_blank_values=True)
+        data = dict(pairs)
+    elif isinstance(body, dict):
+        data = {k: (v[0] if isinstance(v, list) and len(v) == 1 else v) for k, v in body.items()}
+    else:
+        raise TypeError("Тело вебхука: bytes, str или dict")
+
+    for key in _INT_FIELDS:
+        if key in data:
+            try:
+                data[key] = int(data[key])
+            except (TypeError, ValueError):
+                pass
+
+    data["event"] = EVENT_NAMES.get(data.get("type"), "unknown")
+    if data["event"] == "mail_interaction":
+        data["action_name"] = MAIL_ACTIONS.get(data.get("action"), "unknown")
+    if data["event"] == "trigger_event":
+        data["user_vars"] = {k[len("user_var_"):]: v for k, v in data.items() if k.startswith("user_var_")}
+    if isinstance(data.get("user_vars"), str):
+        try:
+            data["user_vars"] = json.loads(data["user_vars"])
+        except ValueError:
+            pass
+    return data

mailganer-0.1.0.dist-info/METADATA

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: mailganer
+Version: 0.1.0
+Summary: Официальный клиент REST API Mailganer: подписчики, списки, рассылки, триггеры, отчёты
+Author-email: Mailganer <api@mailganer.com>
+License-Expression: MIT
+Project-URL: Documentation, https://documentation.mailganer.com/
+Project-URL: API Reference, https://documentation.mailganer.com/reference/
+Project-URL: Homepage, https://mailganer.com
+Keywords: mailganer,email,рассылки,api,email-marketing
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Natural Language :: Russian
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# mailganer
+
+Официальный клиент [REST API Mailganer](https://documentation.mailganer.com/) для Python.
+Версия **0.1.0**, лицензия MIT, Python 3.8+, без внешних зависимостей.
+
+## Установка
+
+```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="ваш_ключ")   # или Mailganer() с MAILGANER_API_KEY
+print(mg.users.balance())            # {'balance': 954.9}
+```
+
+## Подписчики
+
+```python
+# добавить одного
+mg.subscribers.add("user@example.com", source=49767, name="Иван", user_vars={"city": "Москва"})
+
+# до 50 за запрос; если одна запись с ошибкой, не добавится ни одна
+mg.subscribers.add_many([
+    {"email": "a@example.com", "source": 49767, "name": "Аня"},
+    {"email": "b@example.com", "source": 49767, "name": "Боря"},
+])
+
+# v3: подробный ответ по каждой записи, частичный успех не ошибка
+result = mg.subscribers.add_many_v3(rows)
+for row in result["failed"]:
+    print(row["email"], row["errors"])
+
+# найти и обновить
+page = mg.subscribers.list(email="user@example.com")       # одна страница, 25 записей
+for sub in mg.subscribers.list_all(source=49767):            # все страницы подряд
+    ...
+mg.subscribers.update(mg_hash, name="Пётр")                  # по mg_hash
+mg.subscribers.update_by_email("user@example.com", 49767, city="Казань")
+mg.subscribers.unsubscribe(mg_hash)
+```
+
+## Рассылки и триггеры
+
+```python
+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.mailings.stats(draft["public_id"], start_date="2026-10-01", end_date="2026-10-07")
+
+mg.triggers.send(113292, "user@example.com", variables={"order_id": 555})
+mg.segments.send_trigger(245611, trigger_id=145674, ignore_trigger_conditions=True)
+```
+
+## Отчёты
+
+```python
+task = mg.reports.create("csv", site_id=49767)
+mg.reports.wait(task["id"])                       # ждёт state=COMPLETED
+open("list.csv", "wb").write(mg.reports.download(task["id"]))
+```
+
+## Вебхуки
+
+Mailganer шлёт события на URL, заданный `mg.lists.set_webhook(list_id, url)`.
+
+```python
+from mailganer import parse_webhook
+
+@app.post("/mailganer-hook")
+def hook(request):
+    event = parse_webhook(request.body)
+    if event["event"] == "mail_interaction" and event["action_name"] == "clicked":
+        ...
+    return "", 200
+```
+
+`event`: `subscriber_status`, `subscriber_data`, `mail_interaction` (с `action_name`: delivered, opened,
+clicked, unsubscribed, spam_complaint, not_delivered), `trigger_event` (с `user_vars`).
+
+## Постбек
+
+```python
+from mailganer import postback_url
+
+# ссылка для письма: {{public_id}} и {{email_hash}} подставит Mailganer при отправке
+link = postback_url("https://shop.ru/order/done", nps=10)
+```
+
+## Ошибки и лимиты
+
+Все ошибки наследуют `MailganerError`: `AuthenticationError` (401), `PermissionDeniedError` (403),
+`NotFoundError` (404), `ValidationError` (400, подробности по полям в `.errors`), `RateLimitError`,
+`ServerError`. v1-методы, которые сообщают об ошибке в теле с HTTP 200, тоже дают исключение.
+
+При 429, 503 и `throttling` клиент сам ждёт и повторяет запрос (по умолчанию 2 раза, `max_retries`).
+
+```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`. Имена полей совпадают с [справочником API](https://documentation.mailganer.com/reference/).
+Метода нет в библиотеке — `mg.request("GET", "/api/v2/...")`.
+
+## Разработка
+
+```bash
+python -m unittest discover -s tests   # тесты без обращения к API
+```

mailganer-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+mailganer/__init__.py,sha256=w2tJBaITYkPB_ToKB_5C9hbMh6dYSh_ep7Jv4uSJkjs,718
+mailganer/_http.py,sha256=TEG1Ze5ttGRs2WF9OqgjK-MV9i7i1tuf1hBhQ-7umQU,7724
+mailganer/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+mailganer/client.py,sha256=NjqwrRFrarWMhF7a045EwvZ1lQkxEAWkT9PloW_D73Y,2427
+mailganer/errors.py,sha256=Rbj_EQ8JQcDvRi-8HbjxyIO81ioFyc0OqTTntnzel6E,2417
+mailganer/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mailganer/resources.py,sha256=E0AEv6AZjGJFtqSKI-LbqnHkpaR0Tj1IgFUJu218asM,23766
+mailganer/webhooks.py,sha256=uDhWUbQ1A6mkSBKK8-lK-Z8KkCdmNYmIQ5AzZKaDCd0,2778
+mailganer-0.1.0.dist-info/licenses/LICENSE,sha256=zFPfu0qjAr4TDkbw6Vsnm0eLotZLrb0icaC-4yuKUUo,1066
+mailganer-0.1.0.dist-info/METADATA,sha256=VjmHwywxndFocxpXLinVoYpOxiYjBKQH6M3cW52CwC0,5852
+mailganer-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mailganer-0.1.0.dist-info/top_level.txt,sha256=xulTdTgjOXTDA6LP3k9UkiniROyeCGUR0o49cXk0g58,10
+mailganer-0.1.0.dist-info/RECORD,,

mailganer-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mailganer-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mailganer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mailganer-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mailganer