mailganer 0.1.0__tar.gz

mailganer-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,127 @@
+# 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/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mailganer"
+dynamic = ["version"]
+description = "Официальный клиент REST API Mailganer: подписчики, списки, рассылки, триггеры, отчёты"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Mailganer", email = "api@mailganer.com" }]
+requires-python = ">=3.8"
+dependencies = []
+keywords = ["mailganer", "email", "рассылки", "api", "email-marketing"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Natural Language :: Russian",
+    "Topic :: Communications :: Email",
+]
+
+[project.urls]
+Documentation = "https://documentation.mailganer.com/"
+"API Reference" = "https://documentation.mailganer.com/reference/"
+Homepage = "https://mailganer.com"
+
+[tool.setuptools.dynamic]
+version = { attr = "mailganer._version.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+mailganer = ["py.typed"]

mailganer-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mailganer-0.1.0/src/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-0.1.0/src/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-0.1.0/src/mailganer/_version.py

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

mailganer-0.1.0/src/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-0.1.0/src/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