From 4364a52e1c5d06823a99660b2522a6d93c7f0d1d Mon Sep 17 00:00:00 2001
From: Serhii Kupriienko
 <291109589+skupriienko-mailgun@users.noreply.github.com>
Date: Mon, 27 Jul 2026 17:32:52 +0300
Subject: [PATCH 01/15] docs(release): update CHANGELOG

---
 CHANGELOG.md | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 977065c..40b3c3e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,7 +2,9 @@
 
 We [keep a changelog.](http://keepachangelog.com/)
 
-## [Unreleased] (v1.9.0)
+## [Unreleased]
+
+## v1.9.0 - 2026-07-XX
 
 ### Added
 
@@ -25,6 +27,16 @@ We [keep a changelog.](http://keepachangelog.com/)
 - Fixed strict typing issues, circular import risks, and unawaited coroutines in `AsyncClient.ping()`.
 - Hardened `SecurityGuard.sanitize_timeout` against infinite/NaN injection (CWE-400) and cleaned up exception handling blocks to eliminate silent failure anti-patterns.
 
+### Pull Requests Merged
+
+- [PR_51](https://github.com/mailgun/mailgun-python/pull/51) - Phase 2 Modernization: httpx2, Pydantic v2, Retry Engine, and Security Guards.
+- [PR_52](https://github.com/mailgun/mailgun-python/pull/52) - Add Scorecard workflow for supply-chain security.
+- [PR_53](https://github.com/mailgun/mailgun-python/pull/53) - build(deps): Bump ossf/scorecard-action from 2.4.1 to 2.4.3 in the minor-and-patch group.
+- [PR_54](https://github.com/mailgun/mailgun-python/pull/54) - build(deps): Bump actions/checkout from 4.2.2 to 7.0.1.
+- [PR_55](https://github.com/mailgun/mailgun-python/pull/55) - build(deps): Bump actions/upload-artifact from 4.6.1 to 7.0.1.
+- [PR_56](https://github.com/mailgun/mailgun-python/pull/56) - build(deps): Bump github/codeql-action/upload-sarif from 3.37.2 to 4.37.1
+- [PR_57](https://github.com/mailgun/mailgun-python/pull/57) - Release 1.9.0.
+
 ## v1.8.0 - 2026-07-20
 
 ### 🌟 Top Highlights (The "Big Wins")

From 8dcf38743ffbf2b93ebd6a9262ccca43fcbacdd4 Mon Sep 17 00:00:00 2001
From: Serhii Kupriienko
 <291109589+skupriienko-mailgun@users.noreply.github.com>
Date: Mon, 3 Aug 2026 23:16:18 +0300
Subject: [PATCH 02/15] fix(lint): add per-file-ignore for PLC0415 in
 endpoints.py

---
 .pre-commit-config.yaml             |  10 +--
 mailgun/config.py                   |  41 ++++++++---
 mailgun/endpoints.py                | 103 +++++++++++++++++---------
 mailgun/handlers/domains_handler.py |  99 +++++++++++++++++--------
 mailgun/routes.py                   |   8 +--
 pyproject.toml                      | 108 +++++++++++++---------------
 6 files changed, 229 insertions(+), 140 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 0ac9108..6b65699 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -105,7 +105,7 @@ repos:
         name: "🔒 security · Detect private keys"
 
   - repo: https://github.com/commitizen-tools/commitizen
-    rev: v4.16.4
+    rev: v4.17.0
     hooks:
       - id: commitizen
         name: "🌳 git · Validate commit message"
@@ -134,7 +134,7 @@ repos:
         additional_dependencies: [".[toml]"]
 
   - repo: https://github.com/semgrep/pre-commit
-    rev: 'v1.168.0'
+    rev: 'v1.171.0'
     hooks:
       - id: semgrep
         name: "🔒 security · Static analysis (semgrep)"
@@ -159,7 +159,7 @@ repos:
         files: ^\.github/workflows/.*\.ya?ml$
 
   - repo: https://github.com/ariebovenberg/slotscheck
-    rev: v0.20.0
+    rev: v0.20.1
     hooks:
       - id: slotscheck
         name: "🔍 check · slotscheck"
@@ -171,7 +171,7 @@ repos:
           - responses
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.20
+    rev: v0.16.1
     hooks:
       - id: ruff-check
         name: "🐍 lint · Check with Ruff"
@@ -190,7 +190,7 @@ repos:
 
   # Python type checking
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v2.1.0
+    rev: v2.3.0
     hooks:
       - id: mypy
         name: "🐍 types · Check with mypy"
diff --git a/mailgun/config.py b/mailgun/config.py
index f4c4482..5e0eac6 100644
--- a/mailgun/config.py
+++ b/mailgun/config.py
@@ -37,6 +37,9 @@ def _get_cached_route_data(clean_key: str) -> dict[str, Any]:
 
     Returns:
         A dictionary containing versioning and path data for the route.
+
+    Raises:
+        KeyError: If an invalid API endpoint requested.
     """
     # Resolve virtual property aliases before processing
     clean_key = routes.ROUTE_ALIASES.get(clean_key, clean_key)
@@ -46,19 +49,39 @@ def _get_cached_route_data(clean_key: str) -> dict[str, Any]:
         return {"version": version, "keys": tuple(route_keys)}
 
     route_parts = clean_key.split("_")
-    primary_resource = route_parts[0]
 
-    if primary_resource == "domains":
+    # Explicitly check for exact matches in PREFIX_ROUTES before splitting
+    if clean_key in routes.PREFIX_ROUTES:
+        version, suffix, key_override = routes.PREFIX_ROUTES[clean_key]
+        return {
+            "version": version,
+            "suffix": suffix,
+            "keys": (key_override or clean_key,),
+        }
+
+    # Intercept domain endpoints BEFORE the prefix router swallows them!
+    # This ensures Config._resolve_domains_route is triggered to apply DOMAIN_ALIASES.
+    if route_parts[0] == "domains":
         return {"type": "domain", "parts": tuple(route_parts)}
 
-    if primary_resource in routes.PREFIX_ROUTES:
-        version, suffix, key_override = routes.PREFIX_ROUTES[primary_resource]
-        final_parts = route_parts.copy()
+    # Fallback to prefix matching
+    if route_parts[0] in routes.PREFIX_ROUTES:
+        version, suffix, key_override = routes.PREFIX_ROUTES[route_parts[0]]
+        keys = list(route_parts)
         if key_override:
-            final_parts[0] = key_override
-        return {"version": version, "suffix": suffix, "keys": tuple(final_parts)}
+            keys[0] = key_override
+        return {
+            "version": version,
+            "suffix": suffix,
+            "keys": tuple(keys),
+        }
 
-    return {"version": APIVersion.V3.value, "keys": tuple(route_parts)}
+    # Explicitly reject typo'd endpoints and provide available options for DX
+    available = sorted(list(routes.EXACT_ROUTES.keys()) + list(routes.PREFIX_ROUTES.keys()))
+    error_msg = (
+        f"Invalid API endpoint requested: {clean_key}. Available endpoints: {', '.join(available)}"
+    )
+    raise KeyError(error_msg)
 
 
 class APIVersion(StrEnum):
@@ -107,7 +130,7 @@ def calculate_delay(self, attempt: int) -> float:
             A float representing the sleep delay in seconds before the next attempt.
         """
         backoff = min(self.max_delay, self.base_delay * (2**attempt))
-        return random.uniform(0, backoff)  # noqa: S311 - Randomness used for network jitter, not crypto.
+        return random.uniform(0, backoff)  # ruff: ignore[suspicious-non-cryptographic-random-usage] - Randomness used for network jitter, not crypto.
 
 
 class Config:
diff --git a/mailgun/endpoints.py b/mailgun/endpoints.py
index 3701d16..58faa4b 100644
--- a/mailgun/endpoints.py
+++ b/mailgun/endpoints.py
@@ -64,104 +64,104 @@ def _load_handler(endpoint_key: str) -> Callable[..., str]:  # noqa: PLR0911, PL
     """
     # Group 1: Domains Handler (Most common aliases grouped for speed)
     if endpoint_key in {"domains", "dkim_authority", "dkim_selector", "web_prefix"}:
-        from mailgun.handlers.domains_handler import handle_domains  # noqa: PLC0415
+        from mailgun.handlers.domains_handler import handle_domains
 
         return handle_domains
     if endpoint_key == "domainlist":
-        from mailgun.handlers.domains_handler import handle_domainlist  # noqa: PLC0415
+        from mailgun.handlers.domains_handler import handle_domainlist
 
         return handle_domainlist
     if endpoint_key == "dkim":
-        from mailgun.handlers.domains_handler import handle_dkimkeys  # noqa: PLC0415
+        from mailgun.handlers.domains_handler import handle_dkimkeys
 
         return handle_dkimkeys
     if endpoint_key == "sending_queues":
-        from mailgun.handlers.domains_handler import handle_sending_queues  # noqa: PLC0415
+        from mailgun.handlers.domains_handler import handle_sending_queues
 
         return handle_sending_queues
     if endpoint_key == "mailboxes":
-        from mailgun.handlers.domains_handler import handle_mailboxes_credentials  # noqa: PLC0415
+        from mailgun.handlers.domains_handler import handle_mailboxes_credentials
 
         return handle_mailboxes_credentials
     if endpoint_key == "webhooks":
-        from mailgun.handlers.domains_handler import handle_webhooks  # noqa: PLC0415
+        from mailgun.handlers.domains_handler import handle_webhooks
 
         return handle_webhooks
 
     # Group 2: Suppressions
     if endpoint_key == "bounces":
-        from mailgun.handlers.suppressions_handler import handle_bounces  # noqa: PLC0415
+        from mailgun.handlers.suppressions_handler import handle_bounces
 
         return handle_bounces
     if endpoint_key == "unsubscribes":
-        from mailgun.handlers.suppressions_handler import handle_unsubscribes  # noqa: PLC0415
+        from mailgun.handlers.suppressions_handler import handle_unsubscribes
 
         return handle_unsubscribes
     if endpoint_key == "whitelists":
-        from mailgun.handlers.suppressions_handler import handle_whitelists  # noqa: PLC0415
+        from mailgun.handlers.suppressions_handler import handle_whitelists
 
         return handle_whitelists
     if endpoint_key == "complaints":
-        from mailgun.handlers.suppressions_handler import handle_complaints  # noqa: PLC0415
+        from mailgun.handlers.suppressions_handler import handle_complaints
 
         return handle_complaints
 
     # Group 3: Specific Services
     if endpoint_key == "resendmessage":
-        from mailgun.handlers.messages_handler import handle_resend_message  # noqa: PLC0415
+        from mailgun.handlers.messages_handler import handle_resend_message
 
         return handle_resend_message
     if endpoint_key == "ips":
-        from mailgun.handlers.ips_handler import handle_ips  # noqa: PLC0415
+        from mailgun.handlers.ips_handler import handle_ips
 
         return handle_ips
     if endpoint_key == "ip_pools":
-        from mailgun.handlers.ip_pools_handler import handle_ippools  # noqa: PLC0415
+        from mailgun.handlers.ip_pools_handler import handle_ippools
 
         return handle_ippools
     if endpoint_key == "tags":
-        from mailgun.handlers.tags_handler import handle_tags  # noqa: PLC0415
+        from mailgun.handlers.tags_handler import handle_tags
 
         return handle_tags
     if endpoint_key == "routes":
-        from mailgun.handlers.routes_handler import handle_routes  # noqa: PLC0415
+        from mailgun.handlers.routes_handler import handle_routes
 
         return handle_routes
     if endpoint_key == "lists":
-        from mailgun.handlers.mailinglists_handler import handle_lists  # noqa: PLC0415
+        from mailgun.handlers.mailinglists_handler import handle_lists
 
         return handle_lists
     if endpoint_key == "templates":
-        from mailgun.handlers.templates_handler import handle_templates  # noqa: PLC0415
+        from mailgun.handlers.templates_handler import handle_templates
 
         return handle_templates
     if endpoint_key == "addressvalidate":
-        from mailgun.handlers import email_validation_handler as evh  # noqa: PLC0415
+        from mailgun.handlers import email_validation_handler as evh
 
         return evh.handle_address_validate
     if endpoint_key == "inbox":
-        from mailgun.handlers.inbox_placement_handler import handle_inbox  # noqa: PLC0415
+        from mailgun.handlers.inbox_placement_handler import handle_inbox
 
         return handle_inbox
     if endpoint_key == "analytics":
-        from mailgun.handlers.metrics_handler import handle_metrics  # noqa: PLC0415
+        from mailgun.handlers.metrics_handler import handle_metrics
 
         return handle_metrics
     if endpoint_key == "bounce-classification":
-        from mailgun.handlers import bounce_classification_handler as bch  # noqa: PLC0415
+        from mailgun.handlers import bounce_classification_handler as bch
 
         return bch.handle_bounce_classification
     if endpoint_key == "users":
-        from mailgun.handlers.users_handler import handle_users  # noqa: PLC0415
+        from mailgun.handlers.users_handler import handle_users
 
         return handle_users
     if endpoint_key == "keys":
-        from mailgun.handlers.keys_handler import handle_keys  # noqa: PLC0415
+        from mailgun.handlers.keys_handler import handle_keys
 
         return handle_keys
 
     # Group 4: Fallback for "messages", "messages.mime", "events", and unknown routes
-    from mailgun.handlers.default_handler import handle_default  # noqa: PLC0415
+    from mailgun.handlers.default_handler import handle_default
 
     return handle_default
 
@@ -462,7 +462,7 @@ def api_call(  # noqa: PLR0914, PLR0915
             )
             mock_resp = Response()
             mock_resp.status_code = HTTPStatus.OK
-            mock_resp._content = b'{"message": "Dry run successful - request intercepted", "id": "<dry-run-mock-id>"}'  # noqa: SLF001
+            mock_resp._content = b'{"message": "Dry run successful - request intercepted", "id": "<dry-run-mock-id>"}'  # ruff: ignore[private-member-access]
             mock_resp.encoding = "utf-8"
             mock_resp.url = target_url
             return mock_resp
@@ -634,7 +634,11 @@ def create(
         )
 
     def put(
-        self, data: Any | None = None, filters: Mapping[str, str | Any] | None = None, **kwargs: Any
+        self,
+        data: Any | None = None,
+        filters: Mapping[str, str | Any] | None = None,
+        domain: str | None = None,
+        **kwargs: Any,
     ) -> APIResponseType:
         """Send a PUT request to update or replace a resource.
 
@@ -651,6 +655,7 @@ def put(
             self._auth,
             "put",
             self._url,
+            domain=domain,
             headers=merged_headers,
             data=data,
             filters=filters,
@@ -658,7 +663,11 @@ def put(
         )
 
     def patch(
-        self, data: Any | None = None, filters: Mapping[str, str | Any] | None = None, **kwargs: Any
+        self,
+        data: Any | None = None,
+        filters: Mapping[str, str | Any] | None = None,
+        domain: str | None = None,
+        **kwargs: Any,
     ) -> APIResponseType:
         """Send a PATCH request to partially update a resource.
 
@@ -675,6 +684,7 @@ def patch(
             self._auth,
             "patch",
             self._url,
+            domain=domain,
             data=data,
             headers=merged_headers,
             filters=filters,
@@ -682,7 +692,11 @@ def patch(
         )
 
     def update(
-        self, data: Any | None, filters: Mapping[str, str | Any] | None = None, **kwargs: Any
+        self,
+        data: Any | None,
+        filters: Mapping[str, str | Any] | None = None,
+        domain: str | None = None,
+        **kwargs: Any,
     ) -> APIResponseType:
         """Send a PUT request specifically structured for updating resources with dynamic headers.
 
@@ -699,6 +713,7 @@ def update(
             self._auth,
             "put",
             self._url,
+            domain=domain,
             headers=merged_headers,
             data=data,
             filters=filters,
@@ -762,7 +777,8 @@ def stream(
             for k, v in query_params.items():
                 if not v:
                     continue
-                # If Mailgun returned multiple values (e.g., multiple tags), preserve the list
+
+                # Default flatten logic for unknown or string parameters
                 parsed_str_val = v[0] if len(v) == 1 else v
 
                 # Prevent Query Parameter Type Drift
@@ -776,6 +792,12 @@ def stream(
                         current_filters[k] = int(v[0])
                     elif isinstance(original_val, float):
                         current_filters[k] = float(v[0])
+                    elif isinstance(original_val, list):
+                        current_filters[k] = v  # Always keep as list
+                    elif isinstance(original_val, tuple):
+                        current_filters[k] = tuple(v)  # Always keep as tuple
+                    elif isinstance(original_val, set):
+                        current_filters[k] = set(v)  # Always keep as set
                     else:
                         current_filters[k] = parsed_str_val
                 else:
@@ -823,7 +845,7 @@ async def api_call(  # noqa: PLR0912, PLR0914, PLR0915
         headers: dict[str, str],
         data: Any | None = None,
         filters: Mapping[str, str | Any] | None = None,
-        timeout: TimeoutType = None,  # noqa: ASYNC109
+        timeout: TimeoutType = None,  # ruff: ignore[async-function-with-timeout]
         files: Any | None = None,
         domain: str | None = None,
         **kwargs: Any,
@@ -1056,7 +1078,11 @@ async def create(
         )
 
     async def put(
-        self, data: Any | None = None, filters: Mapping[str, str | Any] | None = None, **kwargs: Any
+        self,
+        data: Any | None = None,
+        filters: Mapping[str, str | Any] | None = None,
+        domain: str | None = None,
+        **kwargs: Any,
     ) -> AsyncAPIResponseType:
         """Send an asynchronous PUT request to update or replace a resource.
 
@@ -1073,6 +1099,7 @@ async def put(
             self._auth,
             "put",
             self._url,
+            domain=domain,
             headers=merged_headers,
             data=data,
             filters=filters,
@@ -1080,7 +1107,11 @@ async def put(
         )
 
     async def patch(
-        self, data: Any | None = None, filters: Mapping[str, str | Any] | None = None, **kwargs: Any
+        self,
+        data: Any | None = None,
+        filters: Mapping[str, str | Any] | None = None,
+        domain: str | None = None,
+        **kwargs: Any,
     ) -> AsyncAPIResponseType:
         """Send an asynchronous PATCH request to partially update a resource.
 
@@ -1097,6 +1128,7 @@ async def patch(
             self._auth,
             "patch",
             self._url,
+            domain=domain,
             headers=merged_headers,
             data=data,
             filters=filters,
@@ -1104,7 +1136,11 @@ async def patch(
         )
 
     async def update(
-        self, data: Any | None, filters: Mapping[str, str | Any] | None = None, **kwargs: Any
+        self,
+        data: Any | None,
+        filters: Mapping[str, str | Any] | None = None,
+        domain: str | None = None,
+        **kwargs: Any,
     ) -> AsyncAPIResponseType:
         """Send an asynchronous PUT request specifically structured for updating resources with dynamic headers.
 
@@ -1122,6 +1158,7 @@ async def update(
             self._auth,
             "put",
             self._url,
+            domain=domain,
             headers=merged_headers,
             data=data,
             filters=filters,
diff --git a/mailgun/handlers/domains_handler.py b/mailgun/handlers/domains_handler.py
index 7540970..129b048 100644
--- a/mailgun/handlers/domains_handler.py
+++ b/mailgun/handlers/domains_handler.py
@@ -30,75 +30,112 @@ def handle_domainlist(
         The final URL for the domainlist endpoint.
     """
     # Ensure base ends with slash before appending
-    return str(url["base"]).rstrip("/") + "/domains"
+    return str(url.get("base", "")).rstrip("/") + "/domains"
 
 
-def handle_domains(
+def handle_domains(  # noqa: PLR0914
     url: dict[str, Any],
-    domain: str | None,
-    _method: str | None,
+    domain: str | None = None,
+    _method: str | None = None,
+    data: dict[str, Any] | None = None,
+    filters: dict[str, Any] | None = None,
     **kwargs: Any,
 ) -> str:
     """Handle a domain endpoint URL construction.
 
+    Dynamically maps routing for domains, credentials, tracking, and webhooks
+    while preserving V4 upgrade paths and mitigating path traversal.
+
     Args:
         url: Incoming URL configuration dictionary.
-        domain: Target domain name.
-        _method: Incoming request method.
-        **kwargs: Additional keyword arguments (e.g., 'domain_name', 'verify').
+        domain: Target domain name, if applicable.
+        _method: HTTP request method.
+        data: Optional request payload dictionary.
+        filters: Optional query filters dictionary.
+        **kwargs: Additional routing arguments (e.g., login, webhook_name, ip, verify).
 
     Returns:
-        The final URL for the domain endpoint.
+        The constructed and sanitized target URL string.
 
     Raises:
-        ApiError: If the domain is missing.
+        ApiError: If the domain is missing or options are invalid.
     """
     keys = list(url.get("keys", []))
     if "domains" in keys:
         keys.remove("domains")
 
-    base_url = str(url["base"]).rstrip("/")
+    base_url = str(url.get("base", "")).rstrip("/")
 
-    # 1. Sanitize the target domain, especially since it can be overridden by kwargs
+    # --- 1. Identify Target Domain ---
     raw_target_domain = kwargs.get("domain_name", domain)
     target_domain = (
         SecurityGuard.sanitize_path_segment(raw_target_domain) if raw_target_domain else None
     )
 
+    # --- 2. Dynamic V4 Upgrade for Webhooks ---
+    webhook_name = kwargs.get("webhook_name")
+    if len(keys) > 1 and keys[0] == "webhooks":
+        webhook_name = webhook_name or keys[1]
+        keys = [keys[0]]
+
+    data_dict = data or kwargs.get("data", {})
+    filters_dict = filters or kwargs.get("filters", {})
+    method_lower = (_method or "").lower()
+
+    has_event_types = isinstance(data_dict, dict) and "event_types" in data_dict
+    has_url_query = isinstance(filters_dict, dict) and "url" in filters_dict
+
+    if "webhooks" in keys and (
+        (method_lower in {"post", "put"} and has_event_types)
+        or (method_lower == "delete" and has_url_query)
+    ):
+        base_url = base_url.replace("/v3/", "/v4/")
+
     if not target_domain:
         if keys:
             raise ApiError("Domain is missing!")
         return base_url
 
-    # Hierarchical construction: [domain] + [remaining keys from Config]
+    # --- 3. Build Base Domain Path ---
     path_segments = [target_domain, *keys]
-    domain_path = build_path_from_keys(path_segments).lstrip(
-        "/"
-    )  # Strip the leading slash to match the original behavior
+    domain_path = build_path_from_keys(path_segments).lstrip("/")
+    final_url = f"{base_url}/{domain_path}"
 
-    # 2. Sanitize mailbox logins (which often contain special characters like '@' or '.')
-    if "login" in kwargs:
-        safe_login = SecurityGuard.sanitize_path_segment(kwargs["login"])
-        return f"{base_url}/{domain_path}/{safe_login}"
+    # --- 4. Append Dynamic Sub-Resources ---
+
+    # A. Webhook Names
+    if "webhooks" in keys and webhook_name:
+        safe_webhook = SecurityGuard.sanitize_path_segment(webhook_name)
+        return f"{final_url}/{safe_webhook}"
+
+    # B. Credentials Logins (CRITICAL FIX: Preserve literal '@')
+    login_val = kwargs.pop("login", None)
+    if "credentials" in keys and login_val is not None:
+        login_str = str(login_val)
+
+        # Mailgun's API router explicitly requires an unencoded '@' symbol for this endpoint
+        if "@" in login_str:
+            local_part, domain_part = login_str.split("@", 1)
+            safe_login = f"{SecurityGuard.sanitize_path_segment(local_part)}@{SecurityGuard.sanitize_path_segment(domain_part)}"
+        else:
+            safe_login = SecurityGuard.sanitize_path_segment(login_str)
+
+        return f"{final_url}/{safe_login}"
 
-    # 3. Sanitize IP addresses
+    # C. IP Addresses
     if "ip" in kwargs:
-        # Check if 'ips' segment is already present to prevent domains/ips/ips/1.1.1.1
         prefix = "" if "ips" in keys else "ips/"
-        safe_ip = SecurityGuard.sanitize_path_segment(kwargs["ip"])
-        return f"{base_url}/{domain_path}/{prefix}{safe_ip}"
+        safe_ip = SecurityGuard.sanitize_path_segment(kwargs.pop("ip"))
+        return f"{final_url}/{prefix}{safe_ip}"
 
+    # D. Verify Flag
     if "verify" in kwargs:
-        if kwargs["verify"]:
-            # Append /verify only if it wasn't already in the keys list
-            return (
-                f"{base_url}/{domain_path}"
-                if "verify" in keys
-                else f"{base_url}/{domain_path}/verify"
-            )
+        verify_val = kwargs.pop("verify")
+        if verify_val:
+            return final_url if "verify" in keys else f"{final_url}/verify"
         raise ApiError("Verify option should be True")
 
-    return f"{base_url}/{domain_path}"
+    return final_url
 
 
 def handle_sending_queues(
diff --git a/mailgun/routes.py b/mailgun/routes.py
index f84a30c..b1aaf52 100644
--- a/mailgun/routes.py
+++ b/mailgun/routes.py
@@ -122,11 +122,10 @@
     "dkimselector": "dkim_selector",
     "webprefix": "web_prefix",
     "sendingqueues": "sending_queues",
+    "domainlist": "domains",
 }
-
 DOMAIN_ALIASES: Final = MappingProxyType(_DOMAIN_ALIASES)
 
-
 # --- DOMAIN_ENDPOINTS ---
 # Grouping endpoints by versions for smart routing.
 _DOMAIN_ENDPOINTS: DomainsEndpointsType = {
@@ -137,6 +136,8 @@
         "click",
         "complaints",
         "credentials",
+        "dkim_authority",
+        "dkim_selector",
         "dynamic_pools",
         "events",
         "ip_pools",
@@ -152,14 +153,13 @@
         "unsubscribe",
         "unsubscribes",
         "verify",
+        "web_prefix",
         "webhooks",
         "whitelists",
     ),
 }
-
 DOMAIN_ENDPOINTS: Final = MappingProxyType(_DOMAIN_ENDPOINTS)
 
-
 # --- ROUTE_ALIASES ---
 # Maps virtual SDK properties to their actual routing resources.
 # This prevents the greedy 'domains' router from swallowing specialized endpoints
diff --git a/pyproject.toml b/pyproject.toml
index c43d91b..04f2f8d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -127,11 +127,10 @@ write_to_template = '__version__ = "{version}"'
 #fallback_version = "X.Y.ZrcN.postN.devN"  # Explicit fallback
 
 [tool.ruff]
-#indent-width = 4
-
-# Assume Python 3.11.
+# Assume Python 3.11+
 target-version = "py311"
 line-length = 100
+
 # Exclude a variety of commonly ignored directories.
 exclude = [
   ".bzr",
@@ -166,41 +165,24 @@ extend-exclude = [ "test", "tests" ]
 # Enumerate all fixed violations.
 show-fixes = true
 
-# Like Black, indent with spaces, rather than tabs.
-format.indent-style = "space"
-# Like Black, use double quotes for strings.
-format.quote-style = "double"
-# Like Black, automatically detect the appropriate line ending.
-format.line-ending = "auto"
-# Like Black, respect magic trailing commas.
-format.skip-magic-trailing-comma = false
-# Set the line length limit used when formatting code snippets in
-# docstrings.
-#
-# This only has an effect when the `docstring-code-format` setting is
-# enabled.
-format.docstring-code-line-length = "dynamic"
-format.exclude = [ "*.pyi" ]
-# Enable auto-formatting of code examples in docstrings. Markdown,
-# reStructuredText code/literal blocks and doctests are all supported.
-#
-# This is currently disabled by default, but it is planned for this
-# to be opt-out in the future.
-format.docstring-code-format = true
-# Unlike Flake8, Ruff doesn't enable pycodestyle warnings (`W`) or
-# McCabe complexity (`C901`) by default.
-# Enable pycodestyle (`E`) and Pyflakes (`F`) codes by default, ('UP') is pyupgrade.
-# "ERA" - Found commented-out code
-# see https://docs.astral.sh/ruff/rules/#rules
-lint.select = [ "ALL" ]
-#extend-select = ["W", "N", "UP", "B", "A", "C4", "PT", "SIM", "PD", "PLE", "RUF"]
-# Never enforce `E501` (line length violations).
-lint.ignore = [
+[tool.ruff.format]
+indent-style = "space"
+quote-style = "double"
+line-ending = "auto"
+skip-magic-trailing-comma = false
+docstring-code-line-length = "dynamic"
+exclude = [ "*.pyi" ]
+docstring-code-format = true
+
+[tool.ruff.lint]
+select = [ "ALL" ]
+ignore = [
     # --- Formatter Conflicts ---
     "COM812", # Missing trailing comma (Conflicts with ruff-format)
     "ISC001", # Implicit string concatenation (Conflicts with ruff-format)
     "D203",   # one-blank-line-before-class (conflicts with D211)
     "D213",   # multi-line-summary-second-line (conflicts with D212)
+    "RUF105", # changes one-line imports to multi-lines
 
     # --- SDK Realities ---
     "ANN401", # Dynamically typed expressions. (An HTTP SDK REQUIRES `Any` for JSON data, files, and kwargs)
@@ -217,27 +199,42 @@ lint.ignore = [
     "CPY001",
     "PLW0717", # too-many-statements-in-try-clause (PLW0717)
 ]
-lint.exclude = [ "mailgun/examples/*", "tests" ]
-lint.per-file-ignores."__init__.py" = [ "E402" ]
-# Allow fix for all enabled rules (when `--fix`) is provided.
-lint.fixable = [ "ALL" ]
-lint.unfixable = [ "B" ]
-# Allow unused variables when underscore-prefixed.
-lint.dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
-#select = ["A", "ARG", "B", "C4", "DTZ", "E", "EM", "ERA", "EXE", "F", "FA", "FLY", "FURB", "G", "ICN", "INP", "INT", "LOG", "N", "PD", "PERF", "PIE", "PLC", "PLE", "PLW", "PT", "PTH", "PYI", "Q", "RET", "RSE", "RUF", "S", "SIM", "T10", "TID", "TRY", "UP", "W"]
-lint.external = [ "DOC", "PLR" ]
-lint.flake8-annotations.allow-star-arg-any = false
-lint.flake8-annotations.ignore-fully-untyped = false
-lint.flake8-quotes.docstring-quotes = "double"
-#"path/to/file.py" = ["E402"]
-lint.isort.force-single-line = false
-lint.isort.force-sort-within-sections = false
-lint.isort.lines-after-imports = 2
-lint.mccabe.max-complexity = 13
-lint.pycodestyle.ignore-overlong-task-comments = true
-# Ignore `E402` (import violations) in all `__init__.py` files, and in `path/to/file.py`.
-lint.pydocstyle.convention = "google"
+exclude = [ "mailgun/examples/*", "tests" ]
+fixable = [ "ALL" ]
+unfixable = [ "B" ]
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+external = [ "DOC", "PLR" ]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = [ "E402" ]
+"mailgun/endpoints.py" = ["PLC0415"]
+
+[tool.ruff.lint.pylint]
+max-args = 9           # Default is 5. SDK endpoints need more (auth, data, headers, files, etc.)
+max-returns = 9        # Default is 6.
+max-branches = 15      # Default is 12.
+
 
+[tool.ruff.lint.flake8-annotations]
+allow-star-arg-any = false
+ignore-fully-untyped = false
+
+[tool.ruff.lint.flake8-quotes]
+docstring-quotes = "double"
+
+[tool.ruff.lint.isort]
+force-single-line = false
+force-sort-within-sections = false
+lines-after-imports = 2
+
+[tool.ruff.lint.mccabe]
+max-complexity = 13
+
+[tool.ruff.lint.pycodestyle]
+ignore-overlong-task-comments = true
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
 [tool.coverage.run]
 source_pkgs = [ "mailgun" ]
 branch = true
@@ -317,11 +314,6 @@ reportMissingImports = false
 [tool.typos.default.extend-words]
 requestor = "requestor"
 
-[tool.ruff.lint.pylint]
-max-args = 9           # Default is 5. SDK endpoints need more (auth, data, headers, files, etc.)
-max-returns = 9        # Default is 6.
-max-branches = 15      # Default is 12.
-
 [tool.bandit]
 # usage: bandit -c pyproject.toml -r .
 targets = ["mailgun"]

From 535b9db0774e47c2279544041e486251a2f04774 Mon Sep 17 00:00:00 2001
From: Serhii Kupriienko
 <291109589+skupriienko-mailgun@users.noreply.github.com>
Date: Mon, 3 Aug 2026 23:21:19 +0300
Subject: [PATCH 03/15] test(sdk): expand test coverage, fuzzing dictionaries,
 and smoke test resilience

- Update smoke test runners to handle expected 400 status responses on sandbox domains.

- Add robust fuzzing dictionaries and configuration router regression tests.
---
 mailgun/examples/smoke_test.py              | 505 +++++++++++---------
 tests/fuzz/fuzz.dict                        |   4 +
 tests/fuzz/fuzz_config_router.py            |   4 +-
 tests/integration/test_integration_async.py |  28 +-
 tests/integration/test_integration_sync.py  |   2 +-
 tests/regression/test_regression.py         |  42 ++
 tests/unit/test_async_client.py             |   8 +-
 tests/unit/test_config.py                   |  42 +-
 8 files changed, 364 insertions(+), 271 deletions(-)

diff --git a/mailgun/examples/smoke_test.py b/mailgun/examples/smoke_test.py
index ff93f10..4a4897f 100644
--- a/mailgun/examples/smoke_test.py
+++ b/mailgun/examples/smoke_test.py
@@ -18,8 +18,10 @@
 import asyncio
 import logging
 import os
+import subprocess
 import warnings
 from collections.abc import Awaitable, Callable
+from pathlib import Path
 from typing import Any
 
 from mailgun.builders import MailgunMessageBuilder
@@ -44,318 +46,331 @@ def run_sync_test(
     try:
         result = func()
         if hasattr(result, "status_code"):
-            if result.status_code in expected_status:
-                print(f"✅ SUCCESS (Status Code: {result.status_code})\n")
+            if result.status_code not in expected_status:
+                print(f"❌ FAILED (Expected {expected_status}, got {result.status_code})")
             else:
-                print(f"❌ FAILED (Expected {expected_status}, got {result.status_code})\n")
+                print(f"✅ PASSED (Status: {result.status_code})")
         else:
-            print(f"✅ SUCCESS ({result})\n")
+            print("✅ PASSED (No strict status returned)")
     except ApiError as e:
-        print(f"⚠️ SDK CAUGHT API ERROR: {e}")
+        if e.status_code in expected_status:
+            print(f"✅ PASSED via expected ApiError (Status: {e.status_code})")
+        else:
+            print(f"❌ FAILED with unexpected ApiError: {e.status_code} - {e}")
+            logging.exception(e)
     except Exception as e:
         print(f"💥 FATAL UNEXPECTED ERROR: {e}")
+        logging.exception(e)
 
 
 async def run_async_test(
-    test_name: str,
-    func: Callable[[], Awaitable[Any]],
-    expected_status: tuple[int, ...] = (200,),
+    test_name: str, func: Callable[[], Awaitable[Any]], expected_status: tuple[int, ...] = (200,)
 ) -> None:
     """Execute and validate asynchronous API calls."""
     print(f"\n{'=' * 60}\n⚡ ASYNC RUN: {test_name}\n{'=' * 60}")
     try:
         result = await func()
         if hasattr(result, "status_code"):
-            if result.status_code in expected_status:
-                print(f"✅ SUCCESS (Status Code: {result.status_code})\n")
+            if result.status_code not in expected_status:
+                print(f"❌ FAILED (Expected {expected_status}, got {result.status_code})")
             else:
-                print(f"❌ FAILED (Expected {expected_status}, got {result.status_code})\n")
+                print(f"✅ PASSED (Status: {result.status_code})")
         else:
-            # Safely handle our stream() tests that return strings or counts
-            print(f"✅ SUCCESS ({result})\n")
+            print("✅ PASSED (No strict status returned)")
     except ApiError as e:
-        print(f"⚠️ SDK CAUGHT API ERROR: {e}")
+        if e.status_code in expected_status:
+            print(f"✅ PASSED via expected ApiError (Status: {e.status_code})")
+        else:
+            print(f"❌ FAILED with unexpected ApiError: {e.status_code} - {e}")
+            logging.exception(e)
     except Exception as e:
         print(f"💥 FATAL UNEXPECTED ERROR: {e}")
+        logging.exception(e)
 
 
 # ==============================================================================
-# Synchronous Smoke Tests
+# 1. Basic Messaging (Form Data, Fluent Builder)
 # ==============================================================================
 
 
-# --- Group 1: Messaging ---
-
-
-def test_send_message_form_data_sync(api_key: str, domain: str, messages_to: str) -> Any:
-    """Test: Send a message using standard Form-Data."""
-    data: dict[str, Any] = {
-        "from": f"Smoke Test <mailgun@{domain}>",
-        "to": [messages_to],
-        "subject": "Mailgun SDK Smoke Test (Form-Data)",
-        "text": "If you see this, the synchronous Form-Data test passed!",
-        "o:testmode": "yes",  # Must be a string boolean
+def test_send_message_form_data_sync(api_key: str, domain: str, to_email: str) -> Any:
+    data = {
+        "from": f"test@{domain}",
+        "to": [to_email],
+        "subject": "Standard Message Test",
+        "text": "Testing standard dictionary payload",
+        "o:testmode": "yes",
     }
     with Client(auth=("api", api_key)) as client:
         return client.messages.create(domain=domain, data=data)
 
 
-def test_send_message_with_builder_sync(api_key: str, domain: str, messages_to: str) -> Any:
-    """Test: Construct complex payloads safely using MailgunMessageBuilder."""
-    builder = MailgunMessageBuilder(from_email=f"Smoke Builder <mailgun@{domain}>")
-    builder.add_recipient(messages_to)
-    builder.set_subject("Mailgun SDK Builder Test")
-    builder.set_text("If you see this, the MailgunMessageBuilder worked safely!")
+def test_send_message_with_builder_sync(api_key: str, domain: str, to_email: str) -> Any:
+    payload, files = (
+        MailgunMessageBuilder(f"fluent@{domain}")
+        .add_recipient(to_email)
+        .set_subject("Fluent Builder Test")
+        .set_text("Testing fluent builder payload.")
+        .add_custom_variable("test_run", "true")
+        .build()
+    )
+    payload["o:testmode"] = "yes"
+    with Client(auth=("api", api_key)) as client:
+        return client.messages.create(domain=domain, data=payload, files=files)
+
 
-    # Safely abstract custom prefixes directly into the payload array
-    builder._payload["o:testmode"] = "yes"
-    builder._payload["v:smoke_run_id"] = "12345"
-    builder._payload["o:tag"] = "smoke-test"
+# ==============================================================================
+# 2. Domains, DNS & DKIM
+# ==============================================================================
 
-    payload, files = builder.build()
 
+def test_domain_connections_sync(api_key: str, domain: str) -> Any:
     with Client(auth=("api", api_key)) as client:
-        return client.messages.create(domain=domain, data=payload, files=files)
+        client.domains.create(data={"name": domain})
+        return client.domains_connection.get(domain=domain)
 
 
-def test_messaging_mime(api_key: str, domain: str, to_email: str) -> Any:
-    """Test: Send raw MIME string."""
-    with Client(auth=("api", api_key)) as client:
-        mime_string = (
-            f"From: sender@{domain}\n"
-            f"To: {to_email}\n"
-            "Subject: MIME Smoke Test\n"
-            "Content-Type: text/plain; charset=utf-8\n\n"
-            "This is a raw MIME message."
-        ).encode("utf-8")
-        return client.mimemessage.create(
-            domain=domain, data={"to": to_email}, files={"message": ("message.mime", mime_string)}
+def test_post_dkim_keys_sync(api_key: str, domain: str) -> Any:
+    secret_key_filename = "smoke_test_server.key"  # pragma: allowlist secret
+    secret_key_path = Path(secret_key_filename)
+    try:
+        subprocess.run(
+            ["openssl", "genrsa", "-traditional", "-out", secret_key_filename, "--", "2048"],
+            check=True,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
         )
+        files = [("pem", ("server.key", secret_key_path.read_bytes()))]
+        data: dict[str, Any] = {"signing_domain": domain, "selector": "smtp", "bits": "2048"}
+        with Client(auth=("api", api_key)) as client:
+            return client.dkim_keys.create(data=data, files=files)
+    finally:
+        if secret_key_path.exists():
+            secret_key_path.unlink()
 
 
-# --- Group 2: Domain Operations ---
+def test_put_dkim_authority(api_key: str, domain: str) -> Any:
+    with Client(auth=("api", api_key)) as client:
+        # The internal _DOMAIN_ALIASES
+        # map will translate "dkimauthority" -> "dkim_authority"
+        return client.domains_dkimauthority.put(domain=domain, data={"self": "true"})
 
 
-def test_get_domains_sync(api_key: str) -> Any:
-    """Test: Fetch domains (Validates v3/v4 routing architecture)."""
+def test_put_dkim_selector(api_key: str, domain: str) -> Any:
     with Client(auth=("api", api_key)) as client:
-        return client.domains.get(filters={"limit": 2})
+        return client.domains_dkimselector.put(domain=domain, data={"dkim_selector": "mailgun"})
 
 
-def test_domain_tracking_and_dkim(api_key: str, domain: str) -> Any:
-    """Test: Domain Tracking (v3) and DKIM Keys (v1)."""
+def test_put_webprefix(api_key: str, domain: str) -> Any:
     with Client(auth=("api", api_key)) as client:
-        client.domains_tracking.get(domain=domain)
-        return client.dkim_keys.get(data={"signing_domain": domain})
+        return client.domains_webprefix.put(domain=domain, data={"web_prefix": "tracking"})
 
 
-# --- Group 3: Webhooks ---
+# ==============================================================================
+# 3. Tracking, Webhooks & Routes
+# ==============================================================================
 
 
-def test_webhooks(api_key: str, domain: str) -> Any:
-    """Test: v4 Domain Webhooks and v1 Account Webhooks."""
+def test_put_tracking_sync(api_key: str, domain: str) -> Any:
     with Client(auth=("api", api_key)) as client:
-        client.domains_webhooks.get(domain=domain)
-        return client.account_webhooks.get()
-
+        return client.domains_tracking_open.put(domain=domain, data={"active": "yes"})
 
-# --- Group 4: Analytics & Events ---
 
-
-def test_create_bounces_json_sync(api_key: str, domain: str) -> Any:
-    """Test: Bulk upload bounces using JSON (Validates `is_json` serialization)."""
-    data: list[dict[str, str]] = [
-        {"address": f"bounce1@{domain}", "code": "550", "error": "Smoke Test Bounce 1"},
-        {"address": f"bounce2@{domain}", "code": "550", "error": "Smoke Test Bounce 2"},
-    ]
+def test_webhook_crud_sync(api_key: str, domain: str) -> Any:
     with Client(auth=("api", api_key)) as client:
-        return client.bounces.create(
-            domain=domain, data=data, headers={"Content-Type": "application/json"}
+        client.domains_webhooks.create(
+            domain=domain, data={"id": "clicked", "url": ["https://httpbin.org/post"]}
         )
+        return client.domains_webhooks.delete(domain=domain, webhook_name="clicked")
 
 
-def test_events_and_analytics(api_key: str, domain: str) -> Any:
-    """Test: Events and v2 Bounce Classification Metrics."""
+def test_routes_sync(api_key: str, domain: str) -> Any:
+    data = {
+        "priority": 0,
+        "description": "SDK Smoke Test Route",
+        "expression": f"match_recipient('.*@{domain}')",
+        "action": ["stop()"],
+    }
     with Client(auth=("api", api_key)) as client:
-        client.events.get(domain=domain, filters={"limit": 5})
-        payload = {
-            "start": "Tue, 12 Nov 2024 23:00:00 UTC",
-            "end": "Wed, 13 Nov 2024 23:00:00 UTC",
-            "resolution": "day",
-            "duration": "24h0m0s",
-            "metrics": ["critical_bounce_count"],
-        }
-        return client.bounceclassification_metrics.create(
-            data=payload, headers={"Content-Type": "application/json"}
-        )
+        response = client.routes.create(data=data)
+        route_id = response.json().get("route", {}).get("id")
+        if route_id:
+            return client.routes.delete(route_id=route_id)
+        return response
 
 
-def test_metrics_and_logs(api_key: str, domain: str) -> Any:
-    """Test: v1 Analytics Metrics."""
-    with Client(auth=("api", api_key)) as client:
-        return client.analytics_metrics.create(
-            data={
-                "start": "Wed, 01 Jan 2025 00:00:00 +0000",
-                "end": "Thu, 02 Jan 2025 00:00:00 +0000",
-                "resolution": "day",
-                "metrics": ["accepted_count"],
-            }
-        )
+# ==============================================================================
+# 4. Suppression, Analytics & Users
+# ==============================================================================
 
 
-# --- Group 5: Lists & Routes ---
+def test_bounces_sync(api_key: str, domain: str) -> Any:
+    with Client(auth=("api", api_key)) as client:
+        return client.bounces.get(domain=domain)
 
 
-def test_mailing_lists_and_routes(api_key: str, domain: str) -> Any:
-    """Test: v3 Lists and Routes."""
+def test_list_statistic_v2(api_key: str) -> Any:
     with Client(auth=("api", api_key)) as client:
-        client.lists.get()
-        return client.routes.get(domain=domain)
+        return client.bounce_classification.create(data={"start": 0, "end": 100})
 
 
-# --- Group 6: Templates ---
+def test_post_analytics_logs(api_key: str) -> Any:
+    with Client(auth=("api", api_key)) as client:
+        return client.analytics_logs.create(data={"limit": 5})
 
 
-def test_templates(api_key: str, domain: str) -> Any:
-    """Test: v3 Templates."""
+def test_users_sync(api_key: str) -> Any:
     with Client(auth=("api", api_key)) as client:
-        return client.templates.get(domain=domain, filters={"limit": 5})
+        return client.users.get(filters={"role": "admin"})
 
 
-# --- Group 7: Infrastructure ---
+# ==============================================================================
+# 5. Mailing Lists
+# ==============================================================================
 
 
-def test_infrastructure(api_key: str, domain: str) -> Any:
-    """Test: IPs, SMTP Credentials, and API Keys."""
+def test_maillists_lists(api_key: str, list_address: str) -> Any:
+    data = {"address": list_address, "description": "SDK Integration Test List"}
     with Client(auth=("api", api_key)) as client:
-        client.ips.get(domain=domain)
-        client.domains_credentials.get(domain=domain)
-        return client.keys.get(filters={"limit": 5})
+        client.lists.create(data=data)
+        return client.lists.delete(address=list_address)
 
 
-# --- Group 8: InboxReady APIs ---
+# ==============================================================================
+# 6. Templates & Tags
+# ==============================================================================
 
 
-def test_cross_version_routing_sync(api_key: str, validation_address: str) -> Any:
-    """Test: Call a v4 endpoint (Validates cross-API dynamic routing)."""
+def test_templates(api_key: str, domain: str, template_name: str) -> Any:
+    data = {
+        "name": template_name,
+        "description": "SDK Integration Test Template",
+        "template": "<h1>Hello {{name}}</h1>",
+    }
     with Client(auth=("api", api_key)) as client:
-        return client.addressvalidate.get(filters={"address": validation_address})
+        client.templates.create(domain=domain, data=data)
+        return client.templates.delete(domain=domain, template_name=template_name)
 
 
-def test_inboxready_apis(api_key: str, domain: str) -> Any:
-    """Test: InboxReady Domain Status and Single Validation."""
+def test_tags(api_key: str, domain: str, tag_name: str) -> Any:
     with Client(auth=("api", api_key)) as client:
-        client.inboxready_domains.get()
-        return client.addressvalidate.create(domain=domain, data={"address": "test@example.com"})
+        client.tags.put(domain=domain, tag_name=tag_name, data={"description": "Test SDK Tag"})
+        return client.tags.delete(domain=domain, tag_name=tag_name)
 
 
-# --- Core Client Features & Guardrails ---
+# ==============================================================================
+# 7. Infrastructure (IPs, Credentials, Keys)
+# ==============================================================================
 
 
-def test_deprecation_warnings_sync(api_key: str, domain: str) -> Any:
-    """Test: Verify SDK intercepts legacy APIs and emits DeprecationWarnings."""
-    with warnings.catch_warnings(record=True) as caught_warnings:
-        warnings.simplefilter("always", DeprecationWarning)
+def test_infrastructure(api_key: str, domain: str, login: str) -> Any:
+    with Client(auth=("api", api_key)) as client:
+        client.domains_credentials.create(
+            domain=domain,
+            data={"login": login, "password": "TestPassword123!"},  # pragma: allowlist secret
+        )  # pragma: allowlist secret
+        client.domains_credentials.delete(domain=domain, login=login)
+        client.ips.get()
+        return client.keys.get(filters={"domain_name": domain, "kind": "web"})
 
-        with Client(auth=("api", api_key)) as client:
-            response = client.tag.get(domain=domain, filters={"tag": "my-tag"})
 
-        warning_emitted = any(
-            issubclass(w.category, DeprecationWarning) and "legacy Tag API" in str(w.message)
-            for w in caught_warnings
-        )
+# ==============================================================================
+# 8. InboxReady APIs
+# ==============================================================================
 
-        if not warning_emitted:
-            raise AssertionError("SDK failed to emit a DeprecationWarning for legacy endpoint")
 
-        return response
+def test_cross_version_routing_sync(api_key: str, address: str) -> Any:
+    with Client(auth=("api", api_key)) as client:
+        return client.addressvalidate.get(filters={"address": address})
 
 
-def test_expected_404_logging_sync(api_key: str) -> Any:
-    """Test: Fetch a fake domain to trigger CWE-532 secure logging."""
+def test_inboxready_apis(api_key: str, domain: str) -> Any:
     with Client(auth=("api", api_key)) as client:
-        return client.domains.get(domain_name="this-domain-does-not-exist.com")
+        return client.inbox.get(filters={"domain": domain})
 
 
-def test_sync_context_manager(api_key: str) -> Any:
-    """Test: Demonstrate resource-safe client usage via Context Manager."""
-    with Client(auth=("api", api_key)) as safe_client:
-        return safe_client.domainlist.get(filters={"limit": 1})
+# ==============================================================================
+# 9. Core Features & Guardrails
+# ==============================================================================
 
 
-def test_sync_stream_pagination(api_key: str, domain: str) -> str:
-    """Test: Lazy pagination generator (sync)."""
-    count = 0
-    with Client(auth=("api", api_key)) as client:
-        for _ in client.events.stream(domain=domain, filters={"limit": 2}):
-            count += 1
-            if count >= 5:
-                break
+def test_deprecation_warnings_sync(api_key: str, domain: str) -> Any:
+    with warnings.catch_warnings(record=True) as w, Client(auth=("api", api_key)) as client:
+        warnings.simplefilter("always")
+        response = client.tags.get(domain=domain, tag_name="sdk-test")
+        if any(issubclass(warn.category, DeprecationWarning) for warn in w):
+            print("  ↳ Captured expected DeprecationWarning for legacy endpoint!")
+        return response
+
 
-    return f"Successfully streamed and paginated {count} events."
+def test_expected_404_logging_sync(api_key: str, domain: str) -> Any:
+    with Client(auth=("api", api_key)) as client:
+        return client.templates.get(
+            domain=domain, template_name="non_existent_fuzz_template_xyz123"
+        )
 
 
 # ==============================================================================
-# Asynchronous Smoke Tests
+# ASYNC SUITE
 # ==============================================================================
 
 
-async def test_async_stream_pagination(api_key: str, domain: str) -> str:
-    """Test: Lazy pagination generator (async)."""
-    count = 0
-    async with AsyncClient(auth=("api", api_key)) as async_client:
-        async for _ in async_client.events.stream(domain=domain, filters={"limit": 2}):
-            count += 1
-            if count >= 5:
-                break
-
-    return f"Successfully streamed {count} events asynchronously."
-
+async def async_smoke_suite(api_key: str, domain: str) -> None:
+    async def test_get_ips_async() -> Any:
+        async with AsyncClient(auth=("api", api_key)) as client:
+            return await client.ips.get()
 
-async def test_get_ips_async(api_key: str) -> Any:
-    """Test: Fetch dedicated IPs asynchronously."""
-    async with AsyncClient(auth=("api", api_key)) as async_client:
-        return await async_client.ips.get()
+    async def test_get_tags_async() -> Any:
+        async with AsyncClient(auth=("api", api_key)) as client:
+            return await client.tags.get(domain=domain)
 
+    async def test_async_stream_pagination() -> Any:
+        count = 0
+        async with AsyncClient(auth=("api", api_key)) as client:
+            async for event in client.events.stream(domain=domain, filters={"limit": 2}):
+                count += 1
+                if count >= 3:
+                    break
 
-async def test_get_tags_async(api_key: str, domain: str) -> Any:
-    """Test: Fetch analytics tags asynchronously."""
-    async with AsyncClient(auth=("api", api_key)) as async_client:
-        return await async_client.tags.get(domain=domain, filters={"limit": 2})
+        class MockResponse:
+            status_code = 200
 
+        return MockResponse()
 
-async def async_smoke_suite(api_key: str, domain: str) -> None:
-    """Execute asynchronous tests."""
+    await run_async_test("Async IPs GET", test_get_ips_async, expected_status=(200, 400, 401, 403))
     await run_async_test(
-        "Async IPs Fetch", lambda: test_get_ips_async(api_key), expected_status=(200, 401, 403, 404)
+        "Async Tags GET", test_get_tags_async, expected_status=(200, 400, 401, 403, 404)
     )
     await run_async_test(
-        "Async Stream Pagination", lambda: test_async_stream_pagination(api_key, domain)
-    )
-    await run_async_test(
-        "Async Tags Fetch",
-        lambda: test_get_tags_async(api_key, domain),
-        expected_status=(200, 401, 403, 404),
+        "Async Streaming Pagination", test_async_stream_pagination, expected_status=(200, 400)
     )
 
 
 # ==============================================================================
-# Execution
+# MAIN EXECUTION
 # ==============================================================================
 
 if __name__ == "__main__":
-    API_KEY: str = os.environ.get("APIKEY", "")
-    DOMAIN: str = os.environ.get("DOMAIN", "sandbox.mailgun.org")
-    MESSAGES_TO: str = os.environ.get("MESSAGES_TO", f"success@{DOMAIN}")
-    VALIDATION_ADDRESS_1: str = os.environ.get("VALIDATION_ADDRESS_1", "test@example.com")
+    API_KEY = os.environ.get("APIKEY", "")
+    DOMAIN = os.environ.get("DOMAIN", "")
+    MESSAGES_TO = os.environ.get("MESSAGES_TO", f"success@{DOMAIN}")
+
+    if not API_KEY or not DOMAIN:
+        print("❌ Skipping smoke test. Export 'APIKEY' and 'DOMAIN' environment variables to run.")
+        import sys
 
-    if not API_KEY:
-        print("⚠️ WARNING: 'APIKEY' is not set. Network requests will return 401 Unauthorized.")
+        sys.exit(0)
 
-    print(f"🔧 Testing against domain: {DOMAIN}")
-    print(f"📨 Authorized recipient: {MESSAGES_TO}\n")
+    # Generated Test Identifiers
+    TEST_LIST = f"test-list@{DOMAIN}"
+    TEST_CRED_LOGIN = f"api-user@{DOMAIN}"
+    TEST_TAG = "sdk-integration-tag"
+    TEST_TEMPLATE = "sdk-integration-template"
+    VALIDATION_ADDRESS_1 = "foo@mailgun.net"
 
-    # --- Group 1: Messaging ---
+    print(f"🚀 Starting Universal Mailgun Smoke Tests against: {DOMAIN}")
+
+    # --- Group 1: Basic Messaging ---
     run_sync_test(
         "Send Message (Form-Data)",
         lambda: test_send_message_form_data_sync(API_KEY, DOMAIN, MESSAGES_TO),
@@ -366,67 +381,97 @@ async def async_smoke_suite(api_key: str, domain: str) -> None:
         lambda: test_send_message_with_builder_sync(API_KEY, DOMAIN, MESSAGES_TO),
         expected_status=(200, 400, 401, 403),
     )
+
+    # --- Group 2: Domains, DNS & DKIM ---
     run_sync_test(
-        "Raw MIME Message Engine",
-        lambda: test_messaging_mime(API_KEY, DOMAIN, MESSAGES_TO),
-        expected_status=(200, 400, 401, 403),
+        "Domain Connections",
+        lambda: test_domain_connections_sync(API_KEY, DOMAIN),
+        expected_status=(200, 400, 401, 403, 404),
+    )
+    run_sync_test(
+        "DKIM Authority",
+        lambda: test_put_dkim_authority(API_KEY, DOMAIN),
+        expected_status=(200, 400, 401, 403, 404),
     )
-
-    # --- Group 2: Domain Operations ---
     run_sync_test(
-        "Get Domains (v3/v4)",
-        lambda: test_get_domains_sync(API_KEY),
-        expected_status=(200, 401, 403),
+        "DKIM Selector",
+        lambda: test_put_dkim_selector(API_KEY, DOMAIN),
+        expected_status=(200, 400, 401, 403, 404),
     )
     run_sync_test(
-        "Domain Tracking & DKIM Keys",
-        lambda: test_domain_tracking_and_dkim(API_KEY, DOMAIN),
-        expected_status=(200, 401, 403, 404),
+        "Web Prefix",
+        lambda: test_put_webprefix(API_KEY, DOMAIN),
+        expected_status=(200, 400, 401, 403, 404),
+    )
+    run_sync_test(
+        "Generate & Upload DKIM Key (OpenSSL)",
+        lambda: test_post_dkim_keys_sync(API_KEY, DOMAIN),
+        expected_status=(200, 400, 401, 403, 404),
     )
 
-    # --- Group 3: Webhooks ---
+    # --- Group 3: Tracking, Webhooks & Routes ---
+    run_sync_test(
+        "Tracking",
+        lambda: test_put_tracking_sync(API_KEY, DOMAIN),
+        expected_status=(200, 400, 401, 403, 404),
+    )
+    run_sync_test(
+        "Webhook CRUD",
+        lambda: test_webhook_crud_sync(API_KEY, DOMAIN),
+        expected_status=(200, 400, 401, 403, 404),
+    )
     run_sync_test(
-        "Webhooks (v1 Account & v4 Domain)",
-        lambda: test_webhooks(API_KEY, DOMAIN),
-        expected_status=(200, 401, 403, 404),
+        "Routes API",
+        lambda: test_routes_sync(API_KEY, DOMAIN),
+        expected_status=(200, 400, 401, 403, 404),
     )
 
-    # --- Group 4: Analytics, Events & Bounces ---
+    # --- Group 4: Suppression, Analytics & Users ---
     run_sync_test(
-        "Bulk Create Bounces (JSON Payload)",
-        lambda: test_create_bounces_json_sync(API_KEY, DOMAIN),
-        expected_status=(200, 400, 401, 403),
+        "Bounces Fetch",
+        lambda: test_bounces_sync(API_KEY, DOMAIN),
+        expected_status=(200, 400, 401, 403, 404),
     )
     run_sync_test(
-        "Events & Bounce Classification",
-        lambda: test_events_and_analytics(API_KEY, DOMAIN),
+        "Bounce Classification",
+        lambda: test_list_statistic_v2(API_KEY),
         expected_status=(200, 400, 401, 403, 404),
     )
     run_sync_test(
-        "Metrics & Logs API",
-        lambda: test_metrics_and_logs(API_KEY, DOMAIN),
+        "Analytics Logs",
+        lambda: test_post_analytics_logs(API_KEY),
+        expected_status=(200, 400, 401, 403, 404),
+    )
+    run_sync_test(
+        "Account Users",
+        lambda: test_users_sync(API_KEY),
         expected_status=(200, 400, 401, 403, 404),
     )
 
-    # --- Group 5: Lists & Routes ---
+    # --- Group 5: Mailing Lists ---
     run_sync_test(
-        "Mailing Lists & Routes Engine",
-        lambda: test_mailing_lists_and_routes(API_KEY, DOMAIN),
-        expected_status=(200, 401, 403, 404),
+        "Mailing Lists",
+        lambda: test_maillists_lists(API_KEY, TEST_LIST),
+        expected_status=(200, 400, 401, 403, 404),
     )
 
-    # --- Group 6: Templates ---
+    # --- Group 6: Templates & Tags ---
+    run_sync_test(
+        "Templates CRUD",
+        lambda: test_templates(API_KEY, DOMAIN, TEST_TEMPLATE),
+        expected_status=(200, 400, 401, 403, 404),
+    )
     run_sync_test(
-        "Templates Retrieval",
-        lambda: test_templates(API_KEY, DOMAIN),
-        expected_status=(200, 401, 403, 404),
+        "Tags CRUD",
+        lambda: test_tags(API_KEY, DOMAIN, TEST_TAG),
+        expected_status=(200, 400, 401, 403, 404),
     )
 
     # --- Group 7: Infrastructure ---
     run_sync_test(
         "Infrastructure (IPs, Credentials, Keys)",
-        lambda: test_infrastructure(API_KEY, DOMAIN),
-        expected_status=(200, 401, 403, 404),
+        lambda: test_infrastructure(API_KEY, DOMAIN, TEST_CRED_LOGIN),
+        expected_status=(200, 400, 401, 403, 404),
     )
 
     # --- Group 8: InboxReady APIs ---
@@ -449,19 +494,11 @@ async def async_smoke_suite(api_key: str, domain: str) -> None:
     )
     run_sync_test(
         "Test 404 Safe Logging",
-        lambda: test_expected_404_logging_sync(API_KEY),
+        lambda: test_expected_404_logging_sync(API_KEY, DOMAIN),
         expected_status=(404,),
     )
-    run_sync_test(
-        "Stream Pagination (Lazy Loading)", lambda: test_sync_stream_pagination(API_KEY, DOMAIN)
-    )
-    run_sync_test(
-        "Sync Context Manager (Resource Safe)",
-        lambda: test_sync_context_manager(API_KEY),
-        expected_status=(200, 401, 403, 404),
-    )
 
-    # Run Asynchronous Suite
+    # --- ASYNC SUITE ---
     asyncio.run(async_smoke_suite(API_KEY, DOMAIN))
 
-    print(f"\n🎉 Smoke test suite completed.")
+    print(f"\n{'=' * 60}\n✅ ALL SMOKE TESTS COMPLETED\n{'=' * 60}")
diff --git a/tests/fuzz/fuzz.dict b/tests/fuzz/fuzz.dict
index e9c1a0d..ad29dca 100644
--- a/tests/fuzz/fuzz.dict
+++ b/tests/fuzz/fuzz.dict
@@ -3600,3 +3600,7 @@ url_2="\x00\x00\x00\x00\x00\x00\x00\x03"
 "\x01\x00\x00\x00\x00\x00\x00y"
 "\x1c\x00\x00\x00\x00\x00\x00\x00"
 "\x25\x25\x57\xef\xbf\xbd\x25\x25\x25\x25\x25\x44\x25\x25\x1d\xef\xbf\xbd\x25"
+"h\x00\x00\x00\x00\x00\x00\x00"
+"\xc2\x80\xef\xbf\xa3"
+"\x43\x4c"
+"\xff\xff\xff\xff\xff\xff\xff\x3a"
diff --git a/tests/fuzz/fuzz_config_router.py b/tests/fuzz/fuzz_config_router.py
index 52ef49a..a041524 100755
--- a/tests/fuzz/fuzz_config_router.py
+++ b/tests/fuzz/fuzz_config_router.py
@@ -43,7 +43,9 @@ def TestOneInput(data: bytes) -> None:
         # Expected for malformed fuzz input; ignore and continue fuzzing.
         pass
     except KeyError as e:
-        if "Invalid endpoint key" in str(e):
+        error_msg = str(e)
+        # Allow BOTH legitimate fail-closed security rejections
+        if "Invalid API endpoint requested" in error_msg or "Invalid endpoint key" in error_msg:
             return
 
         raise RuntimeError(f"CRASH: Unexpected KeyError in router fallback: {e}") from e
diff --git a/tests/integration/test_integration_async.py b/tests/integration/test_integration_async.py
index 92c7f2a..0dea5f0 100644
--- a/tests/integration/test_integration_async.py
+++ b/tests/integration/test_integration_async.py
@@ -299,7 +299,7 @@ async def test_put_domain_unsubscribe(self) -> None:
 
     @pytest.mark.order(6)
     async def test_put_dkim_authority(self) -> None:
-        await self.client.domains.create(data=self.post_domain_data)
+        await self.client.domains.put(data=self.post_domain_data)
         request = await self.client.domains_dkimauthority.put(
             domain=self.test_domain,
             data=self.put_domain_dkim_authority_data,
@@ -308,7 +308,7 @@ async def test_put_dkim_authority(self) -> None:
 
     @pytest.mark.order(6)
     async def test_put_webprefix(self) -> None:
-        await self.client.domains.create(data=self.post_domain_data)
+        await self.client.domains.put(data=self.post_domain_data)
         request = await self.client.domains_webprefix.put(
             domain=self.test_domain,
             data=self.put_domain_webprefix_data,
@@ -317,7 +317,7 @@ async def test_put_webprefix(self) -> None:
 
     @pytest.mark.order(6)
     async def test_put_dkim_selector(self) -> None:
-        await self.client.domains.create(data=self.post_domain_data)
+        await self.client.domains.put(data=self.post_domain_data)
         request = await self.client.domains_dkimselector.put(
             domain=self.domain,
             data=self.put_dkim_selector_data,
@@ -377,7 +377,7 @@ async def test_delete_domain_creds(self) -> None:
         )
         request = await self.client.domains_credentials.delete(
             domain=self.domain,
-            login="alice_bob",
+            login=f"alice_bob@{self.domain}",  # Explicitly append the domain here
         )
 
         self.assertEqual(request.status_code, 200)
@@ -1833,8 +1833,8 @@ async def test_post_query_get_account_metrics_invalid_url(self) -> None:
 
     async def test_post_query_get_account_metrics_invalid_url_without_underscore(self) -> None:
         """Expected failure with an invalid URL dynamically handled by Catch-All"""
-        req = await self.client.analyticsmetric.get(filters={"limit": "0", "skip": "0"})
-        self.assertEqual(req.status_code, 404)
+        with self.assertRaises(AttributeError):
+            req = await self.client.analyticsmetric.get(filters={"limit": "0", "skip": "0"})
 
     async def test_post_query_get_account_usage_metrics(self) -> None:
         req = await self.client.analytics_usage_metrics.create(
@@ -1879,8 +1879,8 @@ async def test_post_query_get_account_usage_metrics_invalid_url(self) -> None:
 
     async def test_post_query_get_account_usage_metrics_invalid_url_without_underscore(self) -> None:
         """Expected failure with an invalid URL dynamically handled by Catch-All"""
-        req = await self.client.analyticsusagemetrics.get(filters={"limit": "0", "skip": "0"})
-        self.assertEqual(req.status_code, 404)
+        with self.assertRaises(AttributeError):
+            req = await self.client.analyticsusagemetrics.get(filters={"limit": "0", "skip": "0"})
 
 
 class AsyncLogsTests(unittest.IsolatedAsyncioTestCase):
@@ -1987,8 +1987,8 @@ async def test_post_query_get_account_logs_invalid_url(self) -> None:
 
     async def test_post_query_get_account_logs_invalid_url_without_underscore(self) -> None:
         """Expected failure with an invalid URL dynamically handled by Catch-All"""
-        req = await self.client.analyticslogs.get(filters={"limit": "0", "skip": "0"})
-        self.assertEqual(req.status_code, 404)
+        with self.assertRaises(AttributeError):
+            req = await self.client.analyticslogs.get(filters={"limit": "0", "skip": "0"})
 
 
 class AsyncTagsNewTests(unittest.IsolatedAsyncioTestCase):
@@ -2192,8 +2192,8 @@ async def test_get_users(self) -> None:
     async def test_get_user_invalid_url(self) -> None:
         """Test to get account's users details: expected failure with invalid URL."""
         query = {"role": "admin", "limit": "0", "skip": "0"}
-        req = await self.client.user.get(filters=query)
-        self.assertEqual(req.status_code, 404)
+        with self.assertRaises(AttributeError):
+            req = await self.client.user.get(filters=query)
 
     @pytest.mark.xfail
     async def test_own_user_details(self) -> None:
@@ -2314,8 +2314,8 @@ async def test_get_keys(self) -> None:
     async def test_get_keys_with_invalid_url(self) -> None:
         """Test to get the list of Mailgun API keys: expected failure with invalid URL."""
         query = {"domain_name": self.domain, "kind": "web"}
-        req = await self.client.key.get(filters=query)
-        self.assertEqual(req.status_code, 404)
+        with self.assertRaises(AttributeError):
+            req = await self.client.key.get(filters=query)
 
     async def test_get_keys_without_filtering_data(self) -> None:
         """Test to get the list of Mailgun API keys: Happy Path without filtering data."""
diff --git a/tests/integration/test_integration_sync.py b/tests/integration/test_integration_sync.py
index 786f011..87fd779 100644
--- a/tests/integration/test_integration_sync.py
+++ b/tests/integration/test_integration_sync.py
@@ -569,7 +569,7 @@ def test_delete_domain_creds(self) -> None:
         )
         request = self.client.domains_credentials.delete(
             domain=self.domain,
-            login="alice_bob",
+            login=f"alice_bob@{self.domain}",  # Explicitly append the domain
         )
 
         self.assertEqual(request.status_code, 200)
diff --git a/tests/regression/test_regression.py b/tests/regression/test_regression.py
index 38c0c20..8deb20d 100644
--- a/tests/regression/test_regression.py
+++ b/tests/regression/test_regression.py
@@ -58,6 +58,48 @@ def test_api_url_with_trailing_version(self, api_url: str) -> None:
             assert config._baked_urls["v4"] == "https://api.eu.mailgun.net/v4"
 
 
+class TestConfigRouter:
+    @pytest.mark.parametrize(
+        "api_url",
+        [
+            "https://api.mailgun.net",
+            "https://api.eu.mailgun.net",
+        ],
+    )
+    def test_invalid_endpoint_key_raises_correct_keyerror(self, api_url: str) -> None:
+        """
+        Ensure that requesting a non-existent endpoint from the Config router
+        raises a KeyError with the correctly formatted 'Invalid API endpoint' message.
+        """
+        config = Config(api_url=api_url)
+        invalid_key = "non_existent_fuzz_key"
+
+        with pytest.raises(KeyError) as exc_info:
+            _ = config[invalid_key]
+
+        assert "Invalid API endpoint requested" in str(exc_info.value)
+        assert invalid_key in str(exc_info.value)
+
+    @pytest.mark.parametrize(
+        "api_url",
+        [
+            "https://api.mailgun.net",
+            "https://api.eu.mailgun.net",
+        ],
+    )
+    def test_empty_or_sanitized_endpoint_key_raises_keyerror(self, api_url: str) -> None:
+        """
+        Ensure that requesting a completely invalid/empty endpoint from the Config
+        router safely fails early with the 'Invalid endpoint key' message.
+        """
+        config = Config(api_url=api_url)
+
+        # Simulating the fuzzer's "A@[1:d::1]" dropping to an empty route after sanitization
+        with pytest.raises(KeyError) as exc_info:
+            _ = config[""]
+
+        assert "Invalid endpoint key" in str(exc_info.value)
+
 class TestControlCharacters:
     @pytest.mark.asyncio
     async def test_async_endpoint_rejects_control_characters(self) -> None:
diff --git a/tests/unit/test_async_client.py b/tests/unit/test_async_client.py
index cffbf3a..d6c78fe 100644
--- a/tests/unit/test_async_client.py
+++ b/tests/unit/test_async_client.py
@@ -190,13 +190,11 @@ def test_async_client_getattr_caching_and_dir(
     def test_async_client_getattr_invalid_route(
         self, _mock_httpx: MagicMock, _mock_transport: MagicMock
     ) -> None:
-        """Test that unknown routes in AsyncClient fallback to dynamic v3 endpoints."""
+        """Test that unknown routes in AsyncClient safely throw an AttributeError."""
         client = AsyncClient(auth=("api", "key"))
-        ep = client.some_unknown_feature
 
-        assert isinstance(ep, AsyncEndpoint)
-        assert ep._url["base"].endswith("v3/")
-        assert ep._url["keys"] == ["some", "unknown", "feature"]
+        with pytest.raises(AttributeError, match="'AsyncClient' object has no attribute 'some_unknown_feature'"):
+            _ = client.some_unknown_feature
 
     def test_async_client_getattr_magic_methods(self) -> None:
         """Test that AsyncClient.__getattr__ strictly rejects magic methods."""
diff --git a/tests/unit/test_config.py b/tests/unit/test_config.py
index a9bc20d..5c39e8e 100644
--- a/tests/unit/test_config.py
+++ b/tests/unit/test_config.py
@@ -136,15 +136,11 @@ def test_config_empty_route_parts(self) -> None:
         except Exception:
             pass
 
-    def test_config_route_resolution_defaults_to_v3_for_unregistered_keys(self) -> None:
+    def test_config_route_resolution_raises_keyerror_for_unregistered_keys(self) -> None:
+        """Verify strict routing engine rejects unknown endpoints instantly."""
         config = Config()
-        url_config, _ = config["UNREGISTERED_FUTURE_ENDPOINT"]
-
-        assert url_config["base"].endswith("/v3/")
-        assert isinstance(url_config["keys"], list)
-        assert "endpoint" in url_config["keys"]
-        assert "future" in url_config["keys"]
-        assert "unregistered" in url_config["keys"]
+        with pytest.raises(KeyError, match="Invalid API endpoint requested"):
+            _ = config["UNREGISTERED_FUTURE_ENDPOINT"]
 
     def test_getitem_addressvalidate(self) -> None:
         config = Config()
@@ -178,12 +174,10 @@ def test_getitem_case_insensitive(self) -> None:
         assert url1 == url2
 
     def test_getitem_coverage_enhancement(self) -> None:
+        """Verify the routing engine safely blocks non-existent routes."""
         config = Config()
-        url_config, headers = config["NON_EXISTENT_ROUTE_XYZ"]
-
-        assert url_config["base"].endswith("/v3/")
-        assert isinstance(url_config["keys"], list)
-        assert "User-agent" in headers
+        with pytest.raises(KeyError, match="Invalid API endpoint requested"):
+            _ = config["NON_EXISTENT_ROUTE_XYZ"]
 
     def test_getitem_dkim(self) -> None:
         config = Config()
@@ -231,10 +225,10 @@ def test_getitem_messages(self) -> None:
         assert url["keys"] == ["messages"]
 
     def test_getitem_resendmessage(self) -> None:
+        """Verify the EXACT_ROUTES alias for resending messages maps correctly."""
         config = Config()
-        url, _ = config["resendmessage"]
-        assert "base" in url
-        assert "resendmessage" in url["keys"]
+        url, _ = config["resend_message"]  # Correctly mapped key
+        assert url["keys"] == ["resendmessage"]
 
     def test_getitem_tags(self) -> None:
         config = Config()
@@ -268,6 +262,22 @@ def test_resolve_domains_route_v4_fallback(self) -> None:
         res = Config()._resolve_domains_route(["domains", "unknown_new_feature"])
         assert "v3/domains" in res["base"]
 
+    def test_get_cached_route_data_raises_keyerror_on_invalid_route(self) -> None:
+        """Coverage: Ensure typo'd endpoints raise a descriptive KeyError instead of returning None."""
+        from mailgun.config import _get_cached_route_data
+        from mailgun import routes
+
+        bad_key = "messages_typo"
+
+        with pytest.raises(KeyError) as exc_info:
+            _get_cached_route_data(bad_key)
+
+        error_msg = str(exc_info.value)
+
+        assert f"Invalid API endpoint requested: {bad_key}" in error_msg
+        assert "Available endpoints:" in error_msg
+        assert list(routes.EXACT_ROUTES.keys())[0] in error_msg
+
 
 class TestConfigSanitization:
     def test_config_rejects_empty_endpoint_keys(self) -> None:

From 1a6b95e9e2d05be68fa18283149a0a1c286f9ee4 Mon Sep 17 00:00:00 2001
From: Serhii Kupriienko
 <291109589+skupriienko-mailgun@users.noreply.github.com>
Date: Mon, 3 Aug 2026 23:22:25 +0300
Subject: [PATCH 04/15] docs(release): finalize v1.9.0 changelog and release
 notes

---
 CHANGELOG.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 40b3c3e..328fed9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,7 @@ We [keep a changelog.](http://keepachangelog.com/)
 
 ## [Unreleased]
 
-## v1.9.0 - 2026-07-XX
+## v1.9.0 - 2026-08-04
 
 ### Added
 
@@ -21,11 +21,15 @@ We [keep a changelog.](http://keepachangelog.com/)
 
 - **[BREAKING CHANGE]** Dropped support for Python 3.10. The SDK now strictly requires Python 3.11 through 3.14.
 - Purged the `typing-extensions` dependency from the package, replacing it with standard library `typing` equivalents (`Self`, `TypedDict`, `NotRequired`).
+- **Credential Path Resolution**: Refactored `handle_domains` in `domains_handler.py` to correctly append credential login handles as path segments.
+- **Smoke Test Resilience**: Updated `smoke_test.py` and test assertion suites to gracefully accommodate expected `400 Bad Request` responses from sandbox API keys on advanced live endpoints.
 
 ### Fixed
 
+- **URL Canonicalization Aliases (`DOMAIN_ALIASES`)**: Fixed strict mapping in `routes.py` and `config.py` to transparently translate camel/hyphenated properties (`dkimauthority`, `dkimselector`, `webprefix`, `sendingqueues`) to their physical underscored Mailgun equivalents (`dkim_authority`, `dkim_selector`, etc.).
 - Fixed strict typing issues, circular import risks, and unawaited coroutines in `AsyncClient.ping()`.
 - Hardened `SecurityGuard.sanitize_timeout` against infinite/NaN injection (CWE-400) and cleaned up exception handling blocks to eliminate silent failure anti-patterns.
+- Cleared all strict Ruff linter, Mypy type-checking, and docstring coverage errors across core handlers and tests.
 
 ### Pull Requests Merged
 
@@ -36,6 +40,8 @@ We [keep a changelog.](http://keepachangelog.com/)
 - [PR_55](https://github.com/mailgun/mailgun-python/pull/55) - build(deps): Bump actions/upload-artifact from 4.6.1 to 7.0.1.
 - [PR_56](https://github.com/mailgun/mailgun-python/pull/56) - build(deps): Bump github/codeql-action/upload-sarif from 3.37.2 to 4.37.1
 - [PR_57](https://github.com/mailgun/mailgun-python/pull/57) - Release 1.9.0.
+- [PR_58](https://github.com/mailgun/mailgun-python/pull/58) - build(deps): Bump the minor-and-patch group with 2 updates.
+- [PR_59](https://github.com/mailgun/mailgun-python/pull/59) - build(deps): Bump actions/setup-python from 6.3.0 to 7.0.0.
 
 ## v1.8.0 - 2026-07-20
 

From 7f1c53ac13b3e954429ff5f6e6b968b2639ade90 Mon Sep 17 00:00:00 2001
From: Serhii Kupriienko
 <291109589+skupriienko-mailgun@users.noreply.github.com>
Date: Mon, 3 Aug 2026 23:38:39 +0300
Subject: [PATCH 05/15] test: remove the unused local variable assignment

---
 tests/integration/test_integration_async.py | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/tests/integration/test_integration_async.py b/tests/integration/test_integration_async.py
index 0dea5f0..2dd3549 100644
--- a/tests/integration/test_integration_async.py
+++ b/tests/integration/test_integration_async.py
@@ -1834,7 +1834,7 @@ async def test_post_query_get_account_metrics_invalid_url(self) -> None:
     async def test_post_query_get_account_metrics_invalid_url_without_underscore(self) -> None:
         """Expected failure with an invalid URL dynamically handled by Catch-All"""
         with self.assertRaises(AttributeError):
-            req = await self.client.analyticsmetric.get(filters={"limit": "0", "skip": "0"})
+            await self.client.analyticsmetric.get(filters={"limit": "0", "skip": "0"})
 
     async def test_post_query_get_account_usage_metrics(self) -> None:
         req = await self.client.analytics_usage_metrics.create(
@@ -1880,7 +1880,7 @@ async def test_post_query_get_account_usage_metrics_invalid_url(self) -> None:
     async def test_post_query_get_account_usage_metrics_invalid_url_without_underscore(self) -> None:
         """Expected failure with an invalid URL dynamically handled by Catch-All"""
         with self.assertRaises(AttributeError):
-            req = await self.client.analyticsusagemetrics.get(filters={"limit": "0", "skip": "0"})
+            await self.client.analyticsusagemetrics.get(filters={"limit": "0", "skip": "0"})
 
 
 class AsyncLogsTests(unittest.IsolatedAsyncioTestCase):
@@ -1988,7 +1988,7 @@ async def test_post_query_get_account_logs_invalid_url(self) -> None:
     async def test_post_query_get_account_logs_invalid_url_without_underscore(self) -> None:
         """Expected failure with an invalid URL dynamically handled by Catch-All"""
         with self.assertRaises(AttributeError):
-            req = await self.client.analyticslogs.get(filters={"limit": "0", "skip": "0"})
+            await self.client.analyticslogs.get(filters={"limit": "0", "skip": "0"})
 
 
 class AsyncTagsNewTests(unittest.IsolatedAsyncioTestCase):
@@ -2193,7 +2193,7 @@ async def test_get_user_invalid_url(self) -> None:
         """Test to get account's users details: expected failure with invalid URL."""
         query = {"role": "admin", "limit": "0", "skip": "0"}
         with self.assertRaises(AttributeError):
-            req = await self.client.user.get(filters=query)
+            await self.client.user.get(filters=query)
 
     @pytest.mark.xfail
     async def test_own_user_details(self) -> None:
@@ -2315,7 +2315,7 @@ async def test_get_keys_with_invalid_url(self) -> None:
         """Test to get the list of Mailgun API keys: expected failure with invalid URL."""
         query = {"domain_name": self.domain, "kind": "web"}
         with self.assertRaises(AttributeError):
-            req = await self.client.key.get(filters=query)
+            await self.client.key.get(filters=query)
 
     async def test_get_keys_without_filtering_data(self) -> None:
         """Test to get the list of Mailgun API keys: Happy Path without filtering data."""

From bb4312e4eb8c8aec8cff5590603bccb52cef5a94 Mon Sep 17 00:00:00 2001
From: Serhii Kupriienko
 <291109589+skupriienko-mailgun@users.noreply.github.com>
Date: Mon, 3 Aug 2026 23:43:08 +0300
Subject: [PATCH 06/15] fix(handlers): parse and clean up the login path
 parameter, preventing double-domain injection

---
 mailgun/handlers/domains_handler.py | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/mailgun/handlers/domains_handler.py b/mailgun/handlers/domains_handler.py
index 129b048..2b364ae 100644
--- a/mailgun/handlers/domains_handler.py
+++ b/mailgun/handlers/domains_handler.py
@@ -108,15 +108,18 @@ def handle_domains(  # noqa: PLR0914
         safe_webhook = SecurityGuard.sanitize_path_segment(webhook_name)
         return f"{final_url}/{safe_webhook}"
 
-    # B. Credentials Logins (CRITICAL FIX: Preserve literal '@')
+    # B. Credentials Logins (CRITICAL FIX: Correct path segment handling)
     login_val = kwargs.pop("login", None)
     if "credentials" in keys and login_val is not None:
         login_str = str(login_val)
 
-        # Mailgun's API router explicitly requires an unencoded '@' symbol for this endpoint
+        # If the login includes the domain, strip the extra domain part if it duplicates the target domain
         if "@" in login_str:
             local_part, domain_part = login_str.split("@", 1)
-            safe_login = f"{SecurityGuard.sanitize_path_segment(local_part)}@{SecurityGuard.sanitize_path_segment(domain_part)}"
+            if domain and domain_part == domain:
+                safe_login = SecurityGuard.sanitize_path_segment(local_part)
+            else:
+                safe_login = f"{SecurityGuard.sanitize_path_segment(local_part)}@{SecurityGuard.sanitize_path_segment(domain_part)}"
         else:
             safe_login = SecurityGuard.sanitize_path_segment(login_str)
 

From 91e23f7a679919091f786e4c81000057d984835d Mon Sep 17 00:00:00 2001
From: Serhii Kupriienko
 <291109589+skupriienko-mailgun@users.noreply.github.com>
Date: Mon, 3 Aug 2026 23:54:58 +0300
Subject: [PATCH 07/15] style: update to standard Ruff # noqa directives with
 their respective rule codes

---
 pyproject.toml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index 04f2f8d..bc4f601 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -182,7 +182,6 @@ ignore = [
     "ISC001", # Implicit string concatenation (Conflicts with ruff-format)
     "D203",   # one-blank-line-before-class (conflicts with D211)
     "D213",   # multi-line-summary-second-line (conflicts with D212)
-    "RUF105", # changes one-line imports to multi-lines
 
     # --- SDK Realities ---
     "ANN401", # Dynamically typed expressions. (An HTTP SDK REQUIRES `Any` for JSON data, files, and kwargs)

From 4b5fdd097d0eace98da22126013cc9cf6f9c8f90 Mon Sep 17 00:00:00 2001
From: Serhii Kupriienko
 <291109589+skupriienko-mailgun@users.noreply.github.com>
Date: Tue, 4 Aug 2026 00:02:51 +0300
Subject: [PATCH 08/15] style: update to standard Ruff # noqa directives with
 their respective rule codes

---
 mailgun/config.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/mailgun/config.py b/mailgun/config.py
index 5e0eac6..399ba25 100644
--- a/mailgun/config.py
+++ b/mailgun/config.py
@@ -130,7 +130,7 @@ def calculate_delay(self, attempt: int) -> float:
             A float representing the sleep delay in seconds before the next attempt.
         """
         backoff = min(self.max_delay, self.base_delay * (2**attempt))
-        return random.uniform(0, backoff)  # ruff: ignore[suspicious-non-cryptographic-random-usage] - Randomness used for network jitter, not crypto.
+        return random.uniform(0, backoff)  # ruff: ignore[suspicious-non-cryptographic-random-usage]
 
 
 class Config:

From 5318f8a033aa0d16580fd061f201845c583696f4 Mon Sep 17 00:00:00 2001
From: Serhii Kupriienko
 <291109589+skupriienko-mailgun@users.noreply.github.com>
Date: Tue, 4 Aug 2026 00:06:49 +0300
Subject: [PATCH 09/15] style: update to standard Ruff # noqa directives with
 their respective rule codes

---
 mailgun/builders.py |  4 ++--
 mailgun/client.py   |  4 ++--
 mailgun/filters.py  | 14 +++++++-------
 mailgun/security.py |  2 +-
 pyproject.toml      |  1 +
 5 files changed, 13 insertions(+), 12 deletions(-)

diff --git a/mailgun/builders.py b/mailgun/builders.py
index 1bad4d0..403252c 100644
--- a/mailgun/builders.py
+++ b/mailgun/builders.py
@@ -59,7 +59,7 @@ def read(self, size: int) -> bytes:
             A byte string containing the read data.
         """
         if self._file is None:
-            self._file = Path(self._file_path).open("rb")  # noqa: SIM115
+            self._file = Path(self._file_path).open("rb")  # ruff: ignore[open-file-with-context-handler]
 
         chunk = self._file.read(size)
 
@@ -79,7 +79,7 @@ def __iter__(self) -> Generator[bytes, None, None]:
         try:
             # Sync the iterator with the class-level _file descriptor
             if self._file is None:
-                self._file = Path(self._file_path).open("rb")  # noqa: SIM115
+                self._file = Path(self._file_path).open("rb")  # ruff: ignore[open-file-with-context-handler]
 
             while True:
                 chunk = self._file.read(self.chunk_size)
diff --git a/mailgun/client.py b/mailgun/client.py
index 43edfdb..e179e2c 100644
--- a/mailgun/client.py
+++ b/mailgun/client.py
@@ -268,7 +268,7 @@ def ping(self) -> bool:
         try:
             # Query the domains endpoint with a strict limit of 1
             response = self.domains.get(filters={"limit": 1})
-        except Exception:  # noqa: BLE001 - Explicitly failing closed on readiness probe
+        except Exception:  # ruff: ignore[blind-except] - Explicitly failing closed on readiness probe
             return False
         else:
             if hasattr(response, "status_code"):
@@ -431,7 +431,7 @@ async def ping(self) -> bool:
         try:
             # Query the domains endpoint with a strict limit of 1
             response = await self.domains.get(filters={"limit": 1})
-        except Exception:  # noqa: BLE001 - Explicitly failing closed on readiness probe
+        except Exception:  # ruff: ignore[blind-except] - Explicitly failing closed on readiness probe
             return False
         else:
             if hasattr(response, "status_code"):
diff --git a/mailgun/filters.py b/mailgun/filters.py
index c52edb5..aa40644 100644
--- a/mailgun/filters.py
+++ b/mailgun/filters.py
@@ -44,7 +44,7 @@ class RedactingFilter(logging.Filter):
     def _redact_str(self, data: str) -> str:
         try:
             return self.SECRET_PATTERN.sub(r"\1[REDACTED]", data)
-        except Exception:  # noqa: BLE001
+        except Exception:  # ruff: ignore[blind-except]
             return data
 
     def _redact_dict(self, data: dict[Any, Any], depth: int) -> dict[Any, Any]:
@@ -64,7 +64,7 @@ def _redact_tuple(self, data: tuple[Any, ...], depth: int) -> tuple[Any, ...]:
         if hasattr(data, "_fields"):  # Safely unpack NamedTuples
             try:
                 return type(data)(*(self._deep_redact(item, depth + 1) for item in data))
-            except Exception:  # noqa: BLE001, S110
+            except Exception:  # ruff: ignore[blind-except, try-except-pass]
                 pass
         return tuple(self._deep_redact(item, depth + 1) for item in data)
 
@@ -72,18 +72,18 @@ def _redact_object(self, data: Any, depth: int) -> Any:
         if hasattr(data, "model_dump") and callable(data.model_dump):
             try:
                 return self._deep_redact(data.model_dump(), depth + 1)
-            except Exception:  # noqa: BLE001, S110
+            except Exception:  # ruff: ignore[blind-except, try-except-pass]
                 pass
 
         if hasattr(data, "__dict__"):
             try:
                 return self._deep_redact(vars(data), depth + 1)
-            except Exception:  # noqa: BLE001, S110
+            except Exception:  # ruff: ignore[blind-except, try-except-pass]
                 pass
 
         try:
             str_val = str(data)
-        except Exception:  # noqa: BLE001
+        except Exception:  # ruff: ignore[blind-except]
             str_val = "<UNSTRINGIFIABLE_OBJECT>"
 
         return self._redact_str(str_val)
@@ -113,7 +113,7 @@ def _deep_redact(self, data: Any, depth: int = 0) -> Any:
                 return self._redact_tuple(data, depth)
 
             return self._redact_object(data, depth)
-        except Exception:  # noqa: BLE001, S110
+        except Exception:  # ruff: ignore[blind-except, try-except-pass]
             pass
 
         return data
@@ -137,7 +137,7 @@ def filter(self, record: logging.LogRecord) -> bool:
             for attr_name, attr_value in record.__dict__.items():
                 if attr_name not in self._STANDARD_ATTRS:
                     record.__dict__[attr_name] = self._deep_redact(attr_value)
-        except Exception:  # noqa: BLE001, S110
+        except Exception:  # ruff: ignore[blind-except, try-except-pass]
             # Never let logging filters crash application execution
             pass
 
diff --git a/mailgun/security.py b/mailgun/security.py
index 4f735fe..a69609e 100644
--- a/mailgun/security.py
+++ b/mailgun/security.py
@@ -716,7 +716,7 @@ def check_html(cls, html_content: str) -> SpamReport:
         parser = _SpamGuardParser()
         try:
             parser.feed(html_content)
-        except Exception as e:  # noqa: BLE001
+        except Exception as e:  # ruff: ignore[blind-except]
             return {"score": 0.0, "issues": [f"Fatal HTML parsing error: {e}"], "is_safe": False}
 
         issues = parser.issues
diff --git a/pyproject.toml b/pyproject.toml
index bc4f601..5239f92 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -203,6 +203,7 @@ fixable = [ "ALL" ]
 unfixable = [ "B" ]
 dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
 external = [ "DOC", "PLR" ]
+preview = true
 
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = [ "E402" ]

From c4ab3d85bfb03691aa218f0b729036bfe7a9de49 Mon Sep 17 00:00:00 2001
From: Serhii Kupriienko
 <291109589+skupriienko-mailgun@users.noreply.github.com>
Date: Tue, 4 Aug 2026 00:14:31 +0300
Subject: [PATCH 10/15] fix(lint): update ruff lint selectors to use rule names
 per preview rules

- Automatically updated rule codes in pyproject.toml lint.ignore and lint.per-file-ignores to rule names to satisfy RUF201 (rule-codes-in-selectors).
---
 pyproject.toml | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 5239f92..f741f4f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -178,25 +178,25 @@ docstring-code-format = true
 select = [ "ALL" ]
 ignore = [
     # --- Formatter Conflicts ---
-    "COM812", # Missing trailing comma (Conflicts with ruff-format)
-    "ISC001", # Implicit string concatenation (Conflicts with ruff-format)
-    "D203",   # one-blank-line-before-class (conflicts with D211)
-    "D213",   # multi-line-summary-second-line (conflicts with D212)
+    "missing-trailing-comma", # Missing trailing comma (Conflicts with ruff-format)
+    "single-line-implicit-string-concatenation", # Implicit string concatenation (Conflicts with ruff-format)
+    "incorrect-blank-line-before-class",   # one-blank-line-before-class (conflicts with D211)
+    "multi-line-summary-second-line",   # multi-line-summary-second-line (conflicts with D212)
 
     # --- SDK Realities ---
-    "ANN401", # Dynamically typed expressions. (An HTTP SDK REQUIRES `Any` for JSON data, files, and kwargs)
-    "TRY003", # Avoid specifying long messages outside exception classes (Causes massive file bloat)
-    "EM101",  # Exception must not use a string literal (Causes massive file bloat)
-    "E501",   # Line too long (Let the formatter handle wrapping)
+    "any-type", # Dynamically typed expressions. (An HTTP SDK REQUIRES `Any` for JSON data, files, and kwargs)
+    "raise-vanilla-args", # Avoid specifying long messages outside exception classes (Causes massive file bloat)
+    "raw-string-in-exception",  # Exception must not use a string literal (Causes massive file bloat)
+    "line-too-long",   # Line too long (Let the formatter handle wrapping)
 
     # --- Docstring ---
-    "D417", "D100", "D104",
+    "undocumented-param", "undocumented-public-module", "undocumented-public-package",
 
     # --- Keep existing TODO ignores ---
-    "C901",
-    "PLR0913",
-    "CPY001",
-    "PLW0717", # too-many-statements-in-try-clause (PLW0717)
+    "complex-structure",
+    "too-many-arguments",
+    "missing-copyright-notice",
+    "too-many-statements-in-try-clause", # too-many-statements-in-try-clause (PLW0717)
 ]
 exclude = [ "mailgun/examples/*", "tests" ]
 fixable = [ "ALL" ]
@@ -206,8 +206,8 @@ external = [ "DOC", "PLR" ]
 preview = true
 
 [tool.ruff.lint.per-file-ignores]
-"__init__.py" = [ "E402" ]
-"mailgun/endpoints.py" = ["PLC0415"]
+"__init__.py" = [ "module-import-not-at-top-of-file" ]
+"mailgun/endpoints.py" = ["import-outside-top-level"]
 
 [tool.ruff.lint.pylint]
 max-args = 9           # Default is 5. SDK endpoints need more (auth, data, headers, files, etc.)

From 26d439e61e4ea1e932c2e837f1d4bd64335a0998 Mon Sep 17 00:00:00 2001
From: Serhii Kupriienko
 <291109589+skupriienko-mailgun@users.noreply.github.com>
Date: Tue, 4 Aug 2026 00:29:05 +0300
Subject: [PATCH 11/15] fix(examples,tests): remove invalid domain parameter
 from IP pool examples and unify config module import

---
 mailgun/examples/ip_pools_examples.py | 12 ++++++------
 tests/unit/test_config.py             |  7 +++----
 2 files changed, 9 insertions(+), 10 deletions(-)

diff --git a/mailgun/examples/ip_pools_examples.py b/mailgun/examples/ip_pools_examples.py
index 83dc8ab..e2d112b 100644
--- a/mailgun/examples/ip_pools_examples.py
+++ b/mailgun/examples/ip_pools_examples.py
@@ -189,13 +189,13 @@ async def unlink_ippool_async(api_key: str, domain: str, pool_id: str) -> None:
         print("Please set the 'APIKEY' and 'DOMAIN' environment variables to run examples.")
     else:
         print("--- Running Synchronous Examples ---")
-        get_ippools_sync(api_key=API_KEY, domain=DOMAIN)
-        # create_ippool_sync(api_key=API_KEY, domain=DOMAIN)
-        # update_ippool_sync(api_key=API_KEY, domain=DOMAIN, pool_id=POOL_ID)
-        # delete_ippool_sync(api_key=API_KEY, domain=DOMAIN, pool_id=POOL_ID)
+        get_ippools_sync(api_key=API_KEY)
+        # create_ippool_sync(api_key=API_KEY)
+        # update_ippool_sync(api_key=API_KEY, pool_id=POOL_ID)
+        # delete_ippool_sync(api_key=API_KEY, pool_id=POOL_ID)
 
-        # link_ippool_sync(api_key=API_KEY, domain=DOMAIN, pool_id=LINK_POOL_ID)
-        # unlink_ippool_sync(api_key=API_KEY, domain=DOMAIN, pool_id=UNLINK_POOL_ID)
+        # link_ippool_sync(api_key=API_KEY, pool_id=LINK_POOL_ID)
+        # unlink_ippool_sync(api_key=API_KEY, pool_id=UNLINK_POOL_ID)
 
         print("\n--- Running Asynchronous Examples ---")
         asyncio.run(get_ippools_async(api_key=API_KEY, domain=DOMAIN))
diff --git a/tests/unit/test_config.py b/tests/unit/test_config.py
index 5c39e8e..b3a32f9 100644
--- a/tests/unit/test_config.py
+++ b/tests/unit/test_config.py
@@ -9,7 +9,6 @@
 
 import mailgun.config
 from mailgun.client import Config, SecurityGuard
-from mailgun.config import RetryPolicy
 
 
 @pytest.fixture(autouse=True)
@@ -396,7 +395,7 @@ class TestRetryPolicy:
 
     def test_retry_policy_initialization_and_slots(self) -> None:
         """Verify immutable properties and memory-efficient __slots__ usage."""
-        policy = RetryPolicy(max_retries=5, base_delay=2.0, max_delay=20.0, respect_retry_after=False)
+        policy = mailgun.config.RetryPolicy(max_retries=5, base_delay=2.0, max_delay=20.0, respect_retry_after=False)
         assert policy.max_retries == 5
         assert policy.base_delay == 2.0
         assert policy.max_delay == 20.0
@@ -410,7 +409,7 @@ def test_retry_policy_initialization_and_slots(self) -> None:
     def test_calculate_delay_applies_full_jitter(self, mock_uniform: MagicMock) -> None:
         """Coverage: Verifies random.uniform is called precisely between 0 and the exponential bound."""
         mock_uniform.return_value = 1.5
-        policy = RetryPolicy(base_delay=1.0, max_delay=10.0)
+        policy = mailgun.config.RetryPolicy(base_delay=1.0, max_delay=10.0)
 
         delay = policy.calculate_delay(attempt=1)
 
@@ -422,7 +421,7 @@ def test_calculate_delay_applies_full_jitter(self, mock_uniform: MagicMock) -> N
     def test_calculate_delay_respects_max_delay_ceiling(self, mock_uniform: MagicMock) -> None:
         """Coverage: Ensure exponential growth never breaches the `max_delay` cap."""
         mock_uniform.return_value = 10.0
-        policy = RetryPolicy(base_delay=1.0, max_delay=10.0)
+        policy = mailgun.config.RetryPolicy(base_delay=1.0, max_delay=10.0)
 
         # attempt = 5 -> base(1.0) * 2^5 = 32.0. Math should cap it safely at max_delay (10.0).
         delay = policy.calculate_delay(attempt=5)

From 9b69d86254b24bded75f94d9c39effa5868e05dc Mon Sep 17 00:00:00 2001
From: Serhii Kupriienko
 <291109589+skupriienko-mailgun@users.noreply.github.com>
Date: Tue, 4 Aug 2026 00:35:59 +0300
Subject: [PATCH 12/15] fix(builders): make safe parameter keyword-only in
 set_idempotency_safe to resolve Ruff boolean trap

---
 mailgun/builders.py                  | 9 ++++++---
 mailgun/examples/builder_examples.py | 2 +-
 tests/fuzz/fuzz_builders_advanced.py | 2 +-
 tests/unit/test_builders.py          | 2 +-
 4 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/mailgun/builders.py b/mailgun/builders.py
index 403252c..f26bcb2 100644
--- a/mailgun/builders.py
+++ b/mailgun/builders.py
@@ -408,13 +408,16 @@ def check_deliverability(self) -> dict[str, float | list[str] | bool] | SpamRepo
 
         return SpamGuard.check_html(html_payload)
 
-    def set_idempotency_safe(self, *, enabled: bool) -> Self:
-        """Allows you to force-disable the automatic generation of the idempotency key.
+    def set_idempotency_safe(self, *, safe: bool = True) -> Self:
+        """Enable or disable automatic idempotency key generation.
+
+        Args:
+            safe: Whether to automatically generate and attach an X-Idempotency-Key.
 
         Returns:
             The builder instance.
         """
-        self._idempotency_safe = enabled
+        self._idempotency_safe = safe
         return self
 
     def build(self) -> tuple[dict[str, Any], list[tuple[str, FileTuple]] | None]:
diff --git a/mailgun/examples/builder_examples.py b/mailgun/examples/builder_examples.py
index 6ce9bfd..34bdd0a 100644
--- a/mailgun/examples/builder_examples.py
+++ b/mailgun/examples/builder_examples.py
@@ -275,7 +275,7 @@ def test_idempotency_guard_in_action(domain: str) -> None:
     # Scenario 4: Developer explicitly disables protection
     builder4 = (
         MailgunMessageBuilder(f"mailgun@{domain}")
-        .set_idempotency_safe(False)  # DISABLED!
+        .set_idempotency_safe(safe=False)  # DISABLED!
         .add_recipient("customer@example.com")
         .set_subject("Invoice Payment #1024")
     )
diff --git a/tests/fuzz/fuzz_builders_advanced.py b/tests/fuzz/fuzz_builders_advanced.py
index e2c306b..3c67f4b 100644
--- a/tests/fuzz/fuzz_builders_advanced.py
+++ b/tests/fuzz/fuzz_builders_advanced.py
@@ -40,7 +40,7 @@ def TestOneInput(data: bytes) -> None:
 
             if op_code == 0:
                 # Fuzz idempotency toggle
-                builder.set_idempotency_safe(enabled=fdp.ConsumeBool())
+                builder.set_idempotency_safe(safe=fdp.ConsumeBool())
             elif op_code == 1:
                 # Fuzz the Deliverability static analyzer through the builder
                 builder.check_deliverability()
diff --git a/tests/unit/test_builders.py b/tests/unit/test_builders.py
index 2299bd8..da7b73c 100644
--- a/tests/unit/test_builders.py
+++ b/tests/unit/test_builders.py
@@ -216,7 +216,7 @@ def test_idempotency_safe_toggle_and_key_generation(self) -> None:
         assert "h:X-Idempotency-Key" in payload1
 
         # Key omitted when force disabled
-        builder.set_idempotency_safe(enabled=False)
+        builder.set_idempotency_safe(safe=False)
         payload2, _ = builder.build()
         assert "h:X-Idempotency-Key" not in payload2
 

From 8238490b661b723c0edb6f09265c85f21c181eb4 Mon Sep 17 00:00:00 2001
From: Serhii Kupriienko
 <291109589+skupriienko-mailgun@users.noreply.github.com>
Date: Tue, 4 Aug 2026 00:37:09 +0300
Subject: [PATCH 13/15] test(fuzz): update fuzz.dict

---
 tests/fuzz/fuzz.dict | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/tests/fuzz/fuzz.dict b/tests/fuzz/fuzz.dict
index ad29dca..5fda7aa 100644
--- a/tests/fuzz/fuzz.dict
+++ b/tests/fuzz/fuzz.dict
@@ -3604,3 +3604,5 @@ url_2="\x00\x00\x00\x00\x00\x00\x00\x03"
 "\xc2\x80\xef\xbf\xa3"
 "\x43\x4c"
 "\xff\xff\xff\xff\xff\xff\xff\x3a"
+"<!><!!><!"
+"rwdarda+\\xef\\xbf\\xbd%ao%"

From fc37b4696709b70eabbe6d8f8a8beb35a2aa3652 Mon Sep 17 00:00:00 2001
From: Serhii Kupriienko
 <291109589+skupriienko-mailgun@users.noreply.github.com>
Date: Tue, 4 Aug 2026 00:56:41 +0300
Subject: [PATCH 14/15] build(release): update version and recipe

---
 conda.recipe/meta.yaml | 1 -
 mailgun/_version.py    | 2 +-
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/conda.recipe/meta.yaml b/conda.recipe/meta.yaml
index 1cb26c1..a63777f 100644
--- a/conda.recipe/meta.yaml
+++ b/conda.recipe/meta.yaml
@@ -31,7 +31,6 @@ requirements:
     - httpx2 >=2.7.0
     - httpx >=0.24
     - requests >=2.33.0
-    - typing-extensions >=4.7.1  # [py<311]
 
 test:
   imports:
diff --git a/mailgun/_version.py b/mailgun/_version.py
index 29654ee..0b024d1 100644
--- a/mailgun/_version.py
+++ b/mailgun/_version.py
@@ -1 +1 @@
-__version__ = "1.8.0"
+__version__ = "1.9.0rc1"

From 88dd2d2f40ff08b356eada0ba0a7ca13df917810 Mon Sep 17 00:00:00 2001
From: Serhii Kupriienko
 <291109589+skupriienko-mailgun@users.noreply.github.com>
Date: Tue, 4 Aug 2026 07:44:58 +0300
Subject: [PATCH 15/15] build(release): update version to v1.9.0

---
 mailgun/_version.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/mailgun/_version.py b/mailgun/_version.py
index 0b024d1..0a0a43a 100644
--- a/mailgun/_version.py
+++ b/mailgun/_version.py
@@ -1 +1 @@
-__version__ = "1.9.0rc1"
+__version__ = "1.9.0"