Add support for the Bounce Classification v2 API (#22)

* Add Bounce Classification endpoint

* Update pre-commit hooks

* Add the Bounce Classification section with an example to README.md

* Add class BounceClassificationTests

* Apply linters: remove redundant type ignore

* Update CHANGELOG

Author: skupriienko

.pre-commit-config.yaml

@@ -71,7 +71,7 @@ repos:
         exclude: ^tests
 
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.34.1
+    rev: 0.35.0
     hooks:
       - id: check-github-workflows
         files: ^\.github/workflows/.*\.ya?ml$
@@ -104,24 +104,24 @@ repos:
         exclude: ^tests
 
   - repo: https://github.com/PyCQA/pylint
-    rev: v4.0.2
+    rev: v4.0.3
     hooks:
       - id: pylint
         args:
           - --exit-zero
 
   - repo: https://github.com/asottile/pyupgrade
-    rev: v3.21.0
+    rev: v3.21.1
     hooks:
       - id: pyupgrade
         args: [--py310-plus, --keep-runtime-typing]
 
   - repo: https://github.com/charliermarsh/ruff-pre-commit
     # Ruff version.
-    rev: v0.14.2
+    rev: v0.14.5
     hooks:
       # Run the linter.
-      - id: ruff
+      - id: ruff-check
         args: [--fix, --preview, --exit-non-zero-on-fix]
       # Run the formatter.
       - id: ruff-format

CHANGELOG.md

@@ -4,6 +4,28 @@ We [keep a changelog.](http://keepachangelog.com/)
 
 ## [Unreleased]
 
+## [1.4.0] - 2025-11-XX
+
+### Added
+
+- Add the `Bounce Classification` endpoint:
+  - Add `bounce-classification`, `metrics` to the `bounceclassification` key of special cases in the class `Config`.
+  - Add `bounce_classification_handler.py` to parse Bounce Classification API.
+  - Add `mailgun/examples/bounce_classification_examples.py` with `post_list_statistic_v2()`.
+  - Add `Bounce Classification` sections with an example to `README.md`.
+  - Add class `BounceClassificationTests ` to `tests/tests.py`.
+  - Add docstrings to the test class `BounceClassificationTests` and its methods.
+
+### Changed
+
+- Fix `Metrics`, `Tags New` & `Logs` docstrings in tests.
+- Update CI workflows: update `pre-commit` hooks to the latest versions.
+- Apply linters: remove redundant `type: ignore`.
+
+### Pull Requests Merged
+
+- [PR_22](https://github.com/mailgun/mailgun-python/pull/22) - Add support for the Bounce Classification v2 API
+
 ## [1.3.0] - 2025-11-08
 
 ### Added
@@ -143,4 +165,6 @@ We [keep a changelog.](http://keepachangelog.com/)
 [1.0.1]: https://github.com/mailgun/mailgun-python/releases/tag/v1.0.1
 [1.0.2]: https://github.com/mailgun/mailgun-python/releases/tag/v1.0.2
 [1.1.0]: https://github.com/mailgun/mailgun-python/releases/tag/v1.1.0
-[unreleased]: https://github.com/mailgun/mailgun-python/compare/v1.1.0...HEAD
+[1.2.0]: https://github.com/mailgun/mailgun-python/releases/tag/v1.2.0
+[1.3.0]: https://github.com/mailgun/mailgun-python/releases/tag/v1.3.0
+[unreleased]: https://github.com/mailgun/mailgun-python/compare/v1.3.0...HEAD

README.md

@@ -47,6 +47,8 @@ Check out all the resources and Python code examples in the official
     - [Events](#events)
       - [Retrieves a paginated list of events](#retrieves-a-paginated-list-of-events)
       - [Get events by recipient](#get-events-by-recipient)
+    - [Bounce Classification](#bounce-classification)
+      - [List statistic v2](#list-statistic-v2)
     - [Logs](#logs)
       - [List logs](#list-logs)
     - [Tags New](#tags-new)
@@ -573,6 +575,59 @@ def events_by_recipient() -> None:
     print(req.json())
 ```
 
+### Bounce Classification
+
+[API endpoint](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/bounce-classification).
+
+#### List statistic v2
+
+Items that have no bounces and no delays(classified_failures_count==0) are not returned.
+
+```python
+def post_list_statistic_v2() -> None:
+    """
+    # Bounce Classification
+    # POST /v2/bounce-classification/metrics
+    :return:
+    """
+
+    payload = {
+        "start": "Wed, 12 Nov 2025 23:00:00 UTC",
+        "end": "Thu, 13 Nov 2025 23:00:00 UTC",
+        "resolution": "day",
+        "duration": "24h0m0s",
+        "dimensions": ["entity-name", "domain.name"],
+        "metrics": [
+            "critical_bounce_count",
+            "non_critical_bounce_count",
+            "critical_delay_count",
+            "non_critical_delay_count",
+            "delivered_smtp_count",
+            "classified_failures_count",
+            "critical_bounce_rate",
+            "non_critical_bounce_rate",
+            "critical_delay_rate",
+            "non_critical_delay_rate",
+        ],
+        "filter": {
+            "AND": [
+                {
+                    "attribute": "domain.name",
+                    "comparator": "=",
+                    "values": [{"value": domain}],
+                }
+            ]
+        },
+        "include_subaccounts": True,
+        "pagination": {"sort": "entity-name:asc", "limit": 10},
+    }
+
+    headers = {"Content-Type": "application/json"}
+
+    req = client.bounceclassification_metrics.create(data=payload, headers=headers)
+    print(req.json())
+```
+
 ### Logs
 
 Mailgun keeps track of every inbound and outbound message event and stores this log data. This data can be queried and

mailgun/client.py

@@ -19,6 +19,7 @@
 
 import requests
 
+from mailgun.handlers.bounce_classification_handler import handle_bounce_classification
 from mailgun.handlers.default_handler import handle_default
 from mailgun.handlers.domains_handler import handle_domainlist
 from mailgun.handlers.domains_handler import handle_domains
@@ -71,6 +72,7 @@
     "messages.mime": handle_default,
     "events": handle_default,
     "analytics": handle_metrics,
+    "bounce-classification": handle_bounce_classification,
 }
 
 
@@ -107,6 +109,7 @@ def __getitem__(self, key: str) -> tuple[Any, dict[str, str]]:
         key = key.lower()
         headers = {"User-agent": self.user_agent}
         v1_base = urljoin(self.api_url, "v1/")
+        v2_base = urljoin(self.api_url, "v2/")
         v3_base = urljoin(self.api_url, "v3/")
         v4_base = urljoin(self.api_url, "v4/")
         v5_base = urljoin(self.api_url, "v5/")
@@ -127,6 +130,11 @@ def __getitem__(self, key: str) -> tuple[Any, dict[str, str]]:
                 "base": v1_base,
                 "keys": ["analytics", "usage", "metrics", "logs", "tags", "limits"],
             },
+            # /v2/bounce-classification/metrics
+            "bounceclassification": {
+                "base": v2_base,
+                "keys": ["bounce-classification", "metrics"],
+            },
         }
 
         if key in special_cases:
@@ -139,6 +147,15 @@ def __getitem__(self, key: str) -> tuple[Any, dict[str, str]]:
                 "keys": key.split("_"),
             }, headers
 
+        if "bounceclassification" in key:
+            headers |= {"Content-Type": "application/json"}
+            part1 = key[:6]
+            part2 = key[6:]
+            return {
+                "base": v2_base,
+                "keys": f"{part1}-{part2}".split("_"),
+            }, headers
+
         # Handle DIPP endpoints
         if "subaccount" in key:
             if "ip_pools" in key:

mailgun/examples/bounce_classification_examples.py

@@ -0,0 +1,56 @@
+import os
+
+from mailgun.client import Client
+
+
+key: str = os.environ["APIKEY"]
+domain: str = os.environ["DOMAIN"]
+client: Client = Client(auth=("api", key))
+
+
+def post_list_statistic_v2() -> None:
+    """
+    # Bounce Classification
+    # POST /v2/bounce-classification/metrics
+    :return:
+    """
+
+    payload = {
+        "start": "Wed, 12 Nov 2025 23:00:00 UTC",
+        "end": "Thu, 13 Nov 2025 23:00:00 UTC",
+        "resolution": "day",
+        "duration": "24h0m0s",
+        "dimensions": ["entity-name", "domain.name"],
+        "metrics": [
+            "critical_bounce_count",
+            "non_critical_bounce_count",
+            "critical_delay_count",
+            "non_critical_delay_count",
+            "delivered_smtp_count",
+            "classified_failures_count",
+            "critical_bounce_rate",
+            "non_critical_bounce_rate",
+            "critical_delay_rate",
+            "non_critical_delay_rate",
+        ],
+        "filter": {
+            "AND": [
+                {
+                    "attribute": "domain.name",
+                    "comparator": "=",
+                    "values": [{"value": domain}],
+                }
+            ]
+        },
+        "include_subaccounts": True,
+        "pagination": {"sort": "entity-name:asc", "limit": 10},
+    }
+
+    headers = {"Content-Type": "application/json"}
+
+    req = client.bounceclassification_metrics.create(data=payload, headers=headers)
+    print(req.json())
+
+
+if __name__ == "__main__":
+    post_list_statistic_v2()

mailgun/handlers/bounce_classification_handler.py

@@ -0,0 +1,31 @@
+"""BOUNCE CLASSIFICATION HANDLER.
+
+Doc: https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/bounce-classification
+"""
+
+from __future__ import annotations
+
+from os import path
+from typing import Any
+
+
+def handle_bounce_classification(
+    url: dict[str, Any],
+    _domain: str | None,
+    _method: str | None,
+    **kwargs: Any,
+) -> Any:
+    """Handle Bounce Classification.
+
+    :param url: Incoming URL dictionary
+    :type url: dict
+    :param _domain: Incoming domain (it's not being used for this handler)
+    :type _domain: str
+    :param _method: Incoming request method (it's not being used for this handler)
+    :type _method: str
+    :param kwargs: kwargs
+    :return: final url for Bounce Classification endpoints
+    """
+    final_keys = path.join("/", *url["keys"]) if url["keys"] else ""
+
+    return url["base"][:-1] + final_keys